
<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>pymatgen.core.structure &#8212; pymatgen 2020.7.3 documentation</title>
    <link rel="stylesheet" href="../../../_static/basic.css" type="text/css" />
    <link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
    <script src="../../../_static/jquery.js"></script>
    <script src="../../../_static/underscore.js"></script>
    <script src="../../../_static/doctools.js"></script>
    <script src="../../../_static/language_data.js"></script>
    <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <link rel="index" title="Index" href="../../../genindex.html" />
    <link rel="search" title="Search" href="../../../search.html" />
 
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-33990148-1']);
  _gaq.push(['_trackPageview']);
</script>

  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../../index.html">pymatgen 2020.7.3 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../../index.html" >Module code</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="../../pymatgen.html" accesskey="U">pymatgen</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">pymatgen.core.structure</a></li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
          <div class="body" role="main">
            
  <h1>Source code for pymatgen.core.structure</h1><div class="highlight"><pre>
<span></span><span class="c1"># coding: utf-8</span>
<span class="c1"># Copyright (c) Pymatgen Development Team.</span>
<span class="c1"># Distributed under the terms of the MIT License.</span>

<span class="sd">&quot;&quot;&quot;</span>
<span class="sd">This module provides classes used to define a non-periodic molecule and a</span>
<span class="sd">periodic structure.</span>
<span class="sd">&quot;&quot;&quot;</span>

<span class="kn">import</span> <span class="nn">math</span>
<span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">json</span>
<span class="kn">import</span> <span class="nn">collections</span>
<span class="kn">import</span> <span class="nn">itertools</span>
<span class="kn">from</span> <span class="nn">abc</span> <span class="kn">import</span> <span class="n">ABCMeta</span><span class="p">,</span> <span class="n">abstractmethod</span>
<span class="kn">import</span> <span class="nn">random</span>
<span class="kn">import</span> <span class="nn">warnings</span>
<span class="kn">from</span> <span class="nn">fnmatch</span> <span class="kn">import</span> <span class="n">fnmatch</span>
<span class="kn">import</span> <span class="nn">re</span>
<span class="kn">import</span> <span class="nn">functools</span>
<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Tuple</span><span class="p">,</span> <span class="n">Optional</span><span class="p">,</span> <span class="n">Union</span><span class="p">,</span> <span class="n">Iterator</span><span class="p">,</span> <span class="n">Set</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">,</span> <span class="n">Iterable</span>
<span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>

<span class="kn">from</span> <span class="nn">tabulate</span> <span class="kn">import</span> <span class="n">tabulate</span>

<span class="kn">from</span> <span class="nn">monty.dev</span> <span class="kn">import</span> <span class="n">deprecated</span>
<span class="kn">from</span> <span class="nn">monty.io</span> <span class="kn">import</span> <span class="n">zopen</span>
<span class="kn">from</span> <span class="nn">monty.json</span> <span class="kn">import</span> <span class="n">MSONable</span>

<span class="kn">from</span> <span class="nn">pymatgen.core.operations</span> <span class="kn">import</span> <span class="n">SymmOp</span>
<span class="kn">from</span> <span class="nn">pymatgen.core.lattice</span> <span class="kn">import</span> <span class="n">Lattice</span><span class="p">,</span> <span class="n">get_points_in_spheres</span>
<span class="kn">from</span> <span class="nn">pymatgen.core.periodic_table</span> <span class="kn">import</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">get_el_sp</span><span class="p">,</span> <span class="n">DummySpecie</span>
<span class="kn">from</span> <span class="nn">pymatgen.core.sites</span> <span class="kn">import</span> <span class="n">Site</span><span class="p">,</span> <span class="n">PeriodicSite</span>
<span class="kn">from</span> <span class="nn">pymatgen.core.bonds</span> <span class="kn">import</span> <span class="n">CovalentBond</span><span class="p">,</span> <span class="n">get_bond_length</span>
<span class="kn">from</span> <span class="nn">pymatgen.core.composition</span> <span class="kn">import</span> <span class="n">Composition</span>
<span class="kn">from</span> <span class="nn">pymatgen.util.coord</span> <span class="kn">import</span> <span class="n">get_angle</span><span class="p">,</span> <span class="n">all_distances</span><span class="p">,</span> \
    <span class="n">lattice_points_in_supercell</span>
<span class="kn">from</span> <span class="nn">pymatgen.core.units</span> <span class="kn">import</span> <span class="n">Mass</span><span class="p">,</span> <span class="n">Length</span>


<span class="n">__author__</span> <span class="o">=</span> <span class="s2">&quot;Shyue Ping Ong&quot;</span>
<span class="n">__copyright__</span> <span class="o">=</span> <span class="s2">&quot;Copyright 2011, The Materials Project&quot;</span>
<span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;2.0&quot;</span>
<span class="n">__maintainer__</span> <span class="o">=</span> <span class="s2">&quot;Shyue Ping Ong&quot;</span>
<span class="n">__email__</span> <span class="o">=</span> <span class="s2">&quot;shyuep@gmail.com&quot;</span>
<span class="n">__status__</span> <span class="o">=</span> <span class="s2">&quot;Production&quot;</span>
<span class="n">__date__</span> <span class="o">=</span> <span class="s2">&quot;Sep 23, 2011&quot;</span>


<div class="viewcode-block" id="Neighbor"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Neighbor">[docs]</a><span class="k">class</span> <span class="nc">Neighbor</span><span class="p">(</span><span class="n">Site</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Simple Site subclass to contain a neighboring atom that skips all the</span>
<span class="sd">    unnecessary checks for speed. Can be</span>
<span class="sd">    used as a fixed-length tuple of size 3 to retain backwards compatibility</span>
<span class="sd">    with past use cases.</span>

<span class="sd">        (site, nn_distance, index).</span>

<span class="sd">    In future, usage should be to call attributes, e.g., Neighbor.index,</span>
<span class="sd">    Neighbor.distance, etc.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
                 <span class="n">species</span><span class="p">:</span> <span class="n">Composition</span><span class="p">,</span>
                 <span class="n">coords</span><span class="p">:</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span>
                 <span class="n">properties</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="n">nn_distance</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span>
                 <span class="n">index</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        :param species: Same as Site</span>
<span class="sd">        :param coords: Same as Site, but must be fractional.</span>
<span class="sd">        :param properties: Same as Site</span>
<span class="sd">        :param nn_distance: Distance to some other Site.</span>
<span class="sd">        :param index: Index within structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">coords</span> <span class="o">=</span> <span class="n">coords</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_species</span> <span class="o">=</span> <span class="n">species</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">properties</span> <span class="o">=</span> <span class="n">properties</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">nn_distance</span> <span class="o">=</span> <span class="n">nn_distance</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">index</span> <span class="o">=</span> <span class="n">index</span>

    <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Make neighbor Tuple-like to retain backwards compatibility.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="mi">3</span>

    <span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>  <span class="c1"># type: ignore</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Make neighbor Tuple-like to retain backwards compatibility.</span>

<span class="sd">        :param i:</span>
<span class="sd">        :return:</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">nn_distance</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">index</span><span class="p">)[</span><span class="n">i</span><span class="p">]</span></div>


<div class="viewcode-block" id="PeriodicNeighbor"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.PeriodicNeighbor">[docs]</a><span class="k">class</span> <span class="nc">PeriodicNeighbor</span><span class="p">(</span><span class="n">PeriodicSite</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Simple PeriodicSite subclass to contain a neighboring atom that skips all</span>
<span class="sd">    the unnecessary checks for speed. Can be used as a fixed-length tuple of</span>
<span class="sd">    size 4 to retain backwards compatibility with past use cases.</span>

<span class="sd">        (site, distance, index, image).</span>

<span class="sd">    In future, usage should be to call attributes, e.g., PeriodicNeighbor.index,</span>
<span class="sd">    PeriodicNeighbor.distance, etc.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
                 <span class="n">species</span><span class="p">:</span> <span class="n">Composition</span><span class="p">,</span>
                 <span class="n">coords</span><span class="p">:</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span>
                 <span class="n">lattice</span><span class="p">:</span> <span class="n">Lattice</span><span class="p">,</span>
                 <span class="n">properties</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="n">nn_distance</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span>
                 <span class="n">index</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
                 <span class="n">image</span><span class="p">:</span> <span class="nb">tuple</span> <span class="o">=</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        :param species: Same as PeriodicSite</span>
<span class="sd">        :param coords: Same as PeriodicSite, but must be fractional.</span>
<span class="sd">        :param lattice: Same as PeriodicSite</span>
<span class="sd">        :param properties: Same as PeriodicSite</span>
<span class="sd">        :param nn_distance: Distance to some other Site.</span>
<span class="sd">        :param index: Index within structure.</span>
<span class="sd">        :param image: PeriodicImage</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">lattice</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_frac_coords</span> <span class="o">=</span> <span class="n">coords</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_species</span> <span class="o">=</span> <span class="n">species</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">properties</span> <span class="o">=</span> <span class="n">properties</span> <span class="ow">or</span> <span class="p">{}</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">nn_distance</span> <span class="o">=</span> <span class="n">nn_distance</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">index</span> <span class="o">=</span> <span class="n">index</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">image</span> <span class="o">=</span> <span class="n">image</span>

    <span class="nd">@property</span>  <span class="c1"># type: ignore</span>
    <span class="k">def</span> <span class="nf">coords</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        :return: Cartesian coords.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_cartesian_coords</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_frac_coords</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Make neighbor Tuple-like to retain backwards compatibility.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="mi">4</span>

    <span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>  <span class="c1"># type: ignore</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Make neighbor Tuple-like to retain backwards compatibility.</span>

<span class="sd">        :param i:</span>
<span class="sd">        :return:</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">nn_distance</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">index</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">image</span><span class="p">)[</span><span class="n">i</span><span class="p">]</span></div>


<div class="viewcode-block" id="SiteCollection"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection">[docs]</a><span class="k">class</span> <span class="nc">SiteCollection</span><span class="p">(</span><span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Sequence</span><span class="p">,</span> <span class="n">metaclass</span><span class="o">=</span><span class="n">ABCMeta</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Basic SiteCollection. Essentially a sequence of Sites or PeriodicSites.</span>
<span class="sd">    This serves as a base class for Molecule (a collection of Site, i.e., no</span>
<span class="sd">    periodicity) and Structure (a collection of PeriodicSites, i.e.,</span>
<span class="sd">    periodicity). Not meant to be instantiated directly.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="c1"># Tolerance in Angstrom for determining if sites are too close.</span>
    <span class="n">DISTANCE_TOLERANCE</span> <span class="o">=</span> <span class="mf">0.5</span>

    <span class="nd">@property</span>
    <span class="nd">@abstractmethod</span>
    <span class="k">def</span> <span class="nf">sites</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="n">Site</span><span class="p">,</span> <span class="n">PeriodicSite</span><span class="p">]]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns a tuple of sites.</span>
<span class="sd">        &quot;&quot;&quot;</span>

<div class="viewcode-block" id="SiteCollection.get_distance"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.get_distance">[docs]</a>    <span class="nd">@abstractmethod</span>
    <span class="k">def</span> <span class="nf">get_distance</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">j</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">float</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns distance between sites at index i and j.</span>

<span class="sd">        Args:</span>
<span class="sd">            i: Index of first site</span>
<span class="sd">            j: Index of second site</span>

<span class="sd">        Returns:</span>
<span class="sd">            Distance between sites at index i and index j.</span>
<span class="sd">        &quot;&quot;&quot;</span></div>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">distance_matrix</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns the distance matrix between all sites in the structure. For</span>
<span class="sd">        periodic structures, this is overwritten to return the nearest image</span>
<span class="sd">        distance.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="n">all_distances</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">species</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">Composition</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Only works for ordered structures.</span>
<span class="sd">        Disordered structures will raise an AttributeError.</span>

<span class="sd">        Returns:</span>
<span class="sd">            ([Specie]) List of species at each site of the structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">specie</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">]</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">species_and_occu</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">Composition</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        List of species and occupancies at each site of the structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">]</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">ntypesp</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;Number of types of atoms.&quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">types_of_specie</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">types_of_specie</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">]]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        List of types of specie.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="c1"># Cannot use set since we want a deterministic algorithm.</span>
        <span class="n">types</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[Union[Element, Specie, DummySpecie]]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="k">if</span> <span class="n">v</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">:</span>
                    <span class="n">types</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">sp</span><span class="p">)</span>
        <span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="n">types</span><span class="p">))</span>  <span class="c1"># type: ignore</span>

<div class="viewcode-block" id="SiteCollection.group_by_types"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.group_by_types">[docs]</a>    <span class="k">def</span> <span class="nf">group_by_types</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterator</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="n">Site</span><span class="p">,</span> <span class="n">PeriodicSite</span><span class="p">]]:</span>
        <span class="sd">&quot;&quot;&quot;Iterate over species grouped by type&quot;&quot;&quot;</span>
        <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">types_of_specie</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
                <span class="k">if</span> <span class="n">site</span><span class="o">.</span><span class="n">specie</span> <span class="o">==</span> <span class="n">t</span><span class="p">:</span>
                    <span class="k">yield</span> <span class="n">site</span></div>

<div class="viewcode-block" id="SiteCollection.indices_from_symbol"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.indices_from_symbol">[docs]</a>    <span class="k">def</span> <span class="nf">indices_from_symbol</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">symbol</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="o">...</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns a tuple with the sequential indices of the sites</span>
<span class="sd">        that contain an element with the given chemical symbol.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">tuple</span><span class="p">((</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">specie</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">species</span><span class="p">)</span>
                      <span class="k">if</span> <span class="n">specie</span><span class="o">.</span><span class="n">symbol</span> <span class="o">==</span> <span class="n">symbol</span><span class="p">))</span></div>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">symbol_set</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Tuple with the set of chemical symbols.</span>
<span class="sd">        Note that len(symbol_set) == len(types_of_specie)</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="nb">sorted</span><span class="p">(</span><span class="n">specie</span><span class="o">.</span><span class="n">symbol</span> <span class="k">for</span> <span class="n">specie</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">types_of_specie</span><span class="p">))</span>  <span class="c1"># type: ignore</span>

    <span class="nd">@property</span>  <span class="c1"># type: ignore</span>
    <span class="k">def</span> <span class="nf">atomic_numbers</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;List of atomic numbers.&quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">specie</span><span class="o">.</span><span class="n">Z</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">)</span>  <span class="c1"># type: ignore</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">site_properties</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">List</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns the site properties as a dict of sequences. E.g.,</span>
<span class="sd">        {&quot;magmom&quot;: (5,-5), &quot;charge&quot;: (-4,4)}.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">props</span> <span class="o">=</span> <span class="p">{}</span>  <span class="c1"># type: Dict[str, List]</span>
        <span class="n">prop_keys</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>  <span class="c1"># type: Set[str]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">prop_keys</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>

        <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">prop_keys</span><span class="p">:</span>
            <span class="n">props</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">k</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">]</span>
        <span class="k">return</span> <span class="n">props</span>

    <span class="k">def</span> <span class="fm">__contains__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">site</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span>

    <span class="k">def</span> <span class="fm">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="o">.</span><span class="fm">__iter__</span><span class="p">()</span>

    <span class="k">def</span> <span class="fm">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ind</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">[</span><span class="n">ind</span><span class="p">]</span>

    <span class="k">def</span> <span class="fm">__len__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__hash__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># for now, just use the composition hash code.</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">()</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">num_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Number of sites.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">cart_coords</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns a np.array of the cartesian coordinates of sites in the</span>
<span class="sd">        structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">])</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">formula</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        (str) Returns the formula.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">formula</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">composition</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Composition</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        (Composition) Returns the composition</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">elmap</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>  <span class="c1"># type: Dict[Specie, float]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">species</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">elmap</span><span class="p">[</span><span class="n">species</span><span class="p">]</span> <span class="o">+=</span> <span class="n">occu</span>
        <span class="k">return</span> <span class="n">Composition</span><span class="p">(</span><span class="n">elmap</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">charge</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">float</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns the net charge of the structure based on oxidation states. If</span>
<span class="sd">        Elements are found, a charge of 0 is assumed.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">charge</span> <span class="o">=</span> <span class="mi">0</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">specie</span><span class="p">,</span> <span class="n">amt</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">charge</span> <span class="o">+=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">specie</span><span class="p">,</span> <span class="s2">&quot;oxi_state&quot;</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">*</span> <span class="n">amt</span>
        <span class="k">return</span> <span class="n">charge</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">is_ordered</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Checks if structure is ordered, meaning no partial occupancies in any</span>
<span class="sd">        of the sites.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="nb">all</span><span class="p">((</span><span class="n">site</span><span class="o">.</span><span class="n">is_ordered</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">))</span>

<div class="viewcode-block" id="SiteCollection.get_angle"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.get_angle">[docs]</a>    <span class="k">def</span> <span class="nf">get_angle</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">j</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">k</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">float</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns angle specified by three sites.</span>

<span class="sd">        Args:</span>
<span class="sd">            i: Index of first site.</span>
<span class="sd">            j: Index of second site.</span>
<span class="sd">            k: Index of third site.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Angle in degrees.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">v1</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
        <span class="n">v2</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
        <span class="k">return</span> <span class="n">get_angle</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v2</span><span class="p">,</span> <span class="n">units</span><span class="o">=</span><span class="s2">&quot;degrees&quot;</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.get_dihedral"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.get_dihedral">[docs]</a>    <span class="k">def</span> <span class="nf">get_dihedral</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">j</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">k</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="n">l</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">float</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns dihedral angle specified by four sites.</span>

<span class="sd">        Args:</span>
<span class="sd">            i: Index of first site</span>
<span class="sd">            j: Index of second site</span>
<span class="sd">            k: Index of third site</span>
<span class="sd">            l: Index of fourth site</span>

<span class="sd">        Returns:</span>
<span class="sd">            Dihedral angle in degrees.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">v1</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="bp">self</span><span class="p">[</span><span class="n">l</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
        <span class="n">v2</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="bp">self</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
        <span class="n">v3</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
        <span class="n">v23</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">cross</span><span class="p">(</span><span class="n">v2</span><span class="p">,</span> <span class="n">v3</span><span class="p">)</span>
        <span class="n">v12</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">cross</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v2</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">math</span><span class="o">.</span><span class="n">degrees</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">atan2</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">v2</span><span class="p">)</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v23</span><span class="p">),</span>
                                       <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">v12</span><span class="p">,</span> <span class="n">v23</span><span class="p">)))</span></div>

<div class="viewcode-block" id="SiteCollection.is_valid"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.is_valid">[docs]</a>    <span class="k">def</span> <span class="nf">is_valid</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="n">DISTANCE_TOLERANCE</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        True if SiteCollection does not contain atoms that are too close</span>
<span class="sd">        together. Note that the distance definition is based on type of</span>
<span class="sd">        SiteCollection. Cartesian distances are used for non-periodic</span>
<span class="sd">        Molecules, while PBC is taken into account for periodic structures.</span>

<span class="sd">        Args:</span>
<span class="sd">            tol (float): Distance tolerance. Default is 0.5A.</span>

<span class="sd">        Returns:</span>
<span class="sd">            (bool) True if SiteCollection does not contain atoms that are too</span>
<span class="sd">            close together.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">True</span>
        <span class="n">all_dists</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">distance_matrix</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">triu_indices</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span> <span class="mi">1</span><span class="p">)]</span>
        <span class="k">return</span> <span class="nb">bool</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">min</span><span class="p">(</span><span class="n">all_dists</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">tol</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.to"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.to">[docs]</a>    <span class="nd">@abstractmethod</span>
    <span class="k">def</span> <span class="nf">to</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span> <span class="n">filename</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Generates well-known string representations of SiteCollections (e.g.,</span>
<span class="sd">        molecules / structures). Should return a string type or write to a file.</span>
<span class="sd">        &quot;&quot;&quot;</span></div>

<div class="viewcode-block" id="SiteCollection.from_str"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.from_str">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="nd">@abstractmethod</span>
    <span class="k">def</span> <span class="nf">from_str</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">input_string</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">fmt</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reads in SiteCollection from a string.</span>
<span class="sd">        &quot;&quot;&quot;</span></div>

<div class="viewcode-block" id="SiteCollection.from_file"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.from_file">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="nd">@abstractmethod</span>
    <span class="k">def</span> <span class="nf">from_file</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">filename</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reads in SiteCollection from a filename.</span>
<span class="sd">        &quot;&quot;&quot;</span></div>

<div class="viewcode-block" id="SiteCollection.add_site_property"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.add_site_property">[docs]</a>    <span class="k">def</span> <span class="nf">add_site_property</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">property_name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">values</span><span class="p">:</span> <span class="n">List</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Adds a property to a site.</span>

<span class="sd">        Args:</span>
<span class="sd">            property_name (str): The name of the property to add.</span>
<span class="sd">            values (list): A sequence of values. Must be same length as</span>
<span class="sd">                number of sites.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">values</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Values must be same length as sites.&quot;</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">site</span><span class="p">,</span> <span class="n">val</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">,</span> <span class="n">values</span><span class="p">):</span>
            <span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="n">property_name</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span></div>

<div class="viewcode-block" id="SiteCollection.remove_site_property"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.remove_site_property">[docs]</a>    <span class="k">def</span> <span class="nf">remove_site_property</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">property_name</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Adds a property to a site.</span>

<span class="sd">        Args:</span>
<span class="sd">            property_name (str): The name of the property to add.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">:</span>
            <span class="k">del</span> <span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="n">property_name</span><span class="p">]</span></div>

<div class="viewcode-block" id="SiteCollection.replace_species"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.replace_species">[docs]</a>    <span class="k">def</span> <span class="nf">replace_species</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">species_mapping</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Swap species.</span>

<span class="sd">        Args:</span>
<span class="sd">            species_mapping (dict): dict of species to swap. Species can be</span>
<span class="sd">                elements too. E.g., {Element(&quot;Li&quot;): Element(&quot;Na&quot;)} performs</span>
<span class="sd">                a Li for Na substitution. The second species can be a</span>
<span class="sd">                sp_and_occu dict. For example, a site with 0.5 Si that is</span>
<span class="sd">                passed the mapping {Element(&#39;Si): {Element(&#39;Ge&#39;):0.75,</span>
<span class="sd">                Element(&#39;C&#39;):0.25} } will have .375 Ge and .125 C.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="n">species_mapping</span> <span class="o">=</span> <span class="p">{</span><span class="n">get_el_sp</span><span class="p">(</span><span class="n">k</span><span class="p">):</span> <span class="n">v</span>
                           <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">species_mapping</span><span class="o">.</span><span class="n">items</span><span class="p">()}</span>
        <span class="n">sp_to_replace</span> <span class="o">=</span> <span class="nb">set</span><span class="p">(</span><span class="n">species_mapping</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
        <span class="n">sp_in_structure</span> <span class="o">=</span> <span class="nb">set</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">sp_in_structure</span><span class="o">.</span><span class="n">issuperset</span><span class="p">(</span><span class="n">sp_to_replace</span><span class="p">):</span>
            <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span>
                <span class="s2">&quot;Some species to be substituted are not present in &quot;</span>
                <span class="s2">&quot;structure. Pls check your input. Species to be &quot;</span>
                <span class="s2">&quot;substituted = </span><span class="si">%s</span><span class="s2">; Species in structure = </span><span class="si">%s</span><span class="s2">&quot;</span>
                <span class="o">%</span> <span class="p">(</span><span class="n">sp_to_replace</span><span class="p">,</span> <span class="n">sp_in_structure</span><span class="p">))</span>

        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">sp_to_replace</span><span class="o">.</span><span class="n">intersection</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">):</span>
                <span class="n">c</span> <span class="o">=</span> <span class="n">Composition</span><span class="p">()</span>
                <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">amt</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                    <span class="n">new_sp</span> <span class="o">=</span> <span class="n">species_mapping</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="n">sp</span><span class="p">)</span>
                    <span class="k">try</span><span class="p">:</span>
                        <span class="n">c</span> <span class="o">+=</span> <span class="n">Composition</span><span class="p">(</span><span class="n">new_sp</span><span class="p">)</span> <span class="o">*</span> <span class="n">amt</span>
                    <span class="k">except</span> <span class="ne">Exception</span><span class="p">:</span>
                        <span class="n">c</span> <span class="o">+=</span> <span class="p">{</span><span class="n">new_sp</span><span class="p">:</span> <span class="n">amt</span><span class="p">}</span>
                <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">c</span></div>

<div class="viewcode-block" id="SiteCollection.add_oxidation_state_by_element"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.add_oxidation_state_by_element">[docs]</a>    <span class="k">def</span> <span class="nf">add_oxidation_state_by_element</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">oxidation_states</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">float</span><span class="p">]):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Add oxidation states.</span>

<span class="sd">        Args:</span>
<span class="sd">            oxidation_states (dict): Dict of oxidation states.</span>
<span class="sd">                E.g., {&quot;Li&quot;:1, &quot;Fe&quot;:2, &quot;P&quot;:5, &quot;O&quot;:-2}</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">:</span>
                <span class="n">new_sp</span> <span class="o">=</span> <span class="p">{}</span>
                <span class="k">for</span> <span class="n">el</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                    <span class="n">sym</span> <span class="o">=</span> <span class="n">el</span><span class="o">.</span><span class="n">symbol</span>
                    <span class="n">new_sp</span><span class="p">[</span><span class="n">Specie</span><span class="p">(</span><span class="n">sym</span><span class="p">,</span> <span class="n">oxidation_states</span><span class="p">[</span><span class="n">sym</span><span class="p">])]</span> <span class="o">=</span> <span class="n">occu</span>
                <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">Composition</span><span class="p">(</span><span class="n">new_sp</span><span class="p">)</span>
        <span class="k">except</span> <span class="ne">KeyError</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Oxidation state of all elements must be &quot;</span>
                             <span class="s2">&quot;specified in the dictionary.&quot;</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.add_oxidation_state_by_site"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.add_oxidation_state_by_site">[docs]</a>    <span class="k">def</span> <span class="nf">add_oxidation_state_by_site</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">oxidation_states</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">float</span><span class="p">]):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Add oxidation states to a structure by site.</span>

<span class="sd">        Args:</span>
<span class="sd">            oxidation_states (list): List of oxidation states.</span>
<span class="sd">                E.g., [1, 1, 1, 1, 2, 2, 2, 2, 5, 5, 5, 5, -2, -2, -2, -2]</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">oxidation_states</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Oxidation states of all sites must be &quot;</span>
                             <span class="s2">&quot;specified.&quot;</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">site</span><span class="p">,</span> <span class="n">ox</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">,</span> <span class="n">oxidation_states</span><span class="p">):</span>
            <span class="n">new_sp</span> <span class="o">=</span> <span class="p">{}</span>
            <span class="k">for</span> <span class="n">el</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">sym</span> <span class="o">=</span> <span class="n">el</span><span class="o">.</span><span class="n">symbol</span>
                <span class="n">new_sp</span><span class="p">[</span><span class="n">Specie</span><span class="p">(</span><span class="n">sym</span><span class="p">,</span> <span class="n">ox</span><span class="p">)]</span> <span class="o">=</span> <span class="n">occu</span>
            <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">Composition</span><span class="p">(</span><span class="n">new_sp</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.remove_oxidation_states"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.remove_oxidation_states">[docs]</a>    <span class="k">def</span> <span class="nf">remove_oxidation_states</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Removes oxidation states from a structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">:</span>
            <span class="n">new_sp</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>
            <span class="k">for</span> <span class="n">el</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">sym</span> <span class="o">=</span> <span class="n">el</span><span class="o">.</span><span class="n">symbol</span>
                <span class="n">new_sp</span><span class="p">[</span><span class="n">Element</span><span class="p">(</span><span class="n">sym</span><span class="p">)]</span> <span class="o">+=</span> <span class="n">occu</span>
            <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">Composition</span><span class="p">(</span><span class="n">new_sp</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.add_oxidation_state_by_guess"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.add_oxidation_state_by_guess">[docs]</a>    <span class="k">def</span> <span class="nf">add_oxidation_state_by_guess</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Decorates the structure with oxidation state, guessing</span>
<span class="sd">        using Composition.oxi_state_guesses()</span>

<span class="sd">        Args:</span>
<span class="sd">            **kwargs: parameters to pass into oxi_state_guesses()</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">oxid_guess</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">oxi_state_guesses</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="n">oxid_guess</span> <span class="o">=</span> <span class="n">oxid_guess</span> <span class="ow">or</span> <span class="p">[{</span><span class="n">e</span><span class="o">.</span><span class="n">symbol</span><span class="p">:</span> <span class="mi">0</span> <span class="k">for</span> <span class="n">e</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="p">}]</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">add_oxidation_state_by_element</span><span class="p">(</span><span class="n">oxid_guess</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span></div>

<div class="viewcode-block" id="SiteCollection.add_spin_by_element"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.add_spin_by_element">[docs]</a>    <span class="k">def</span> <span class="nf">add_spin_by_element</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">spins</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">float</span><span class="p">]):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Add spin states to a structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            spins (dict): Dict of spins associated with elements or species,</span>
<span class="sd">                e.g. {&quot;Ni&quot;:+5} or {&quot;Ni2+&quot;:5}</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">:</span>
            <span class="n">new_sp</span> <span class="o">=</span> <span class="p">{}</span>
            <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">sym</span> <span class="o">=</span> <span class="n">sp</span><span class="o">.</span><span class="n">symbol</span>
                <span class="n">oxi_state</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="s2">&quot;oxi_state&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
                <span class="n">new_sp</span><span class="p">[</span><span class="n">Specie</span><span class="p">(</span><span class="n">sym</span><span class="p">,</span> <span class="n">oxidation_state</span><span class="o">=</span><span class="n">oxi_state</span><span class="p">,</span>
                              <span class="n">properties</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;spin&#39;</span><span class="p">:</span> <span class="n">spins</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">sp</span><span class="p">),</span> <span class="n">spins</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">sym</span><span class="p">,</span> <span class="kc">None</span><span class="p">))})]</span> <span class="o">=</span> <span class="n">occu</span>
            <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">Composition</span><span class="p">(</span><span class="n">new_sp</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.add_spin_by_site"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.add_spin_by_site">[docs]</a>    <span class="k">def</span> <span class="nf">add_spin_by_site</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">spins</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">float</span><span class="p">]):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Add spin states to a structure by site.</span>

<span class="sd">        Args:</span>
<span class="sd">            spins (list): List of spins</span>
<span class="sd">                E.g., [+5, -5, 0, 0]</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">spins</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Spin of all sites must be &quot;</span>
                             <span class="s2">&quot;specified in the dictionary.&quot;</span><span class="p">)</span>

        <span class="k">for</span> <span class="n">site</span><span class="p">,</span> <span class="n">spin</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">,</span> <span class="n">spins</span><span class="p">):</span>
            <span class="n">new_sp</span> <span class="o">=</span> <span class="p">{}</span>
            <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">sym</span> <span class="o">=</span> <span class="n">sp</span><span class="o">.</span><span class="n">symbol</span>
                <span class="n">oxi_state</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="s2">&quot;oxi_state&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
                <span class="n">new_sp</span><span class="p">[</span><span class="n">Specie</span><span class="p">(</span><span class="n">sym</span><span class="p">,</span> <span class="n">oxidation_state</span><span class="o">=</span><span class="n">oxi_state</span><span class="p">,</span>
                              <span class="n">properties</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;spin&#39;</span><span class="p">:</span> <span class="n">spin</span><span class="p">})]</span> <span class="o">=</span> <span class="n">occu</span>
            <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">Composition</span><span class="p">(</span><span class="n">new_sp</span><span class="p">)</span></div>

<div class="viewcode-block" id="SiteCollection.remove_spin"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.remove_spin">[docs]</a>    <span class="k">def</span> <span class="nf">remove_spin</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Removes spin states from a structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span><span class="p">:</span>
            <span class="n">new_sp</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">float</span><span class="p">)</span>
            <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">occu</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">oxi_state</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="s2">&quot;oxi_state&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
                <span class="n">new_sp</span><span class="p">[</span><span class="n">Specie</span><span class="p">(</span><span class="n">sp</span><span class="o">.</span><span class="n">symbol</span><span class="p">,</span> <span class="n">oxidation_state</span><span class="o">=</span><span class="n">oxi_state</span><span class="p">)]</span> <span class="o">+=</span> <span class="n">occu</span>
            <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">new_sp</span></div>

<div class="viewcode-block" id="SiteCollection.extract_cluster"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.SiteCollection.extract_cluster">[docs]</a>    <span class="k">def</span> <span class="nf">extract_cluster</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">target_sites</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">Site</span><span class="p">],</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sa">r</span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Extracts a cluster of atoms based on bond lengths</span>

<span class="sd">        Args:</span>
<span class="sd">            target_sites ([Site]): List of initial sites to nucleate cluster.</span>
<span class="sd">            **kwargs: kwargs passed through to CovalentBond.is_bonded.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [Site/PeriodicSite] Cluster of atoms.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">cluster</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">target_sites</span><span class="p">)</span>
        <span class="n">others</span> <span class="o">=</span> <span class="p">[</span><span class="n">site</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span> <span class="k">if</span> <span class="n">site</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">cluster</span><span class="p">]</span>
        <span class="n">size</span> <span class="o">=</span> <span class="mi">0</span>
        <span class="k">while</span> <span class="nb">len</span><span class="p">(</span><span class="n">cluster</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">size</span><span class="p">:</span>
            <span class="n">size</span> <span class="o">=</span> <span class="nb">len</span><span class="p">(</span><span class="n">cluster</span><span class="p">)</span>
            <span class="n">new_others</span> <span class="o">=</span> <span class="p">[]</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">others</span><span class="p">:</span>
                <span class="k">for</span> <span class="n">site2</span> <span class="ow">in</span> <span class="n">cluster</span><span class="p">:</span>
                    <span class="k">if</span> <span class="n">CovalentBond</span><span class="o">.</span><span class="n">is_bonded</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">site2</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
                        <span class="n">cluster</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site</span><span class="p">)</span>
                        <span class="k">break</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="n">new_others</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site</span><span class="p">)</span>
            <span class="n">others</span> <span class="o">=</span> <span class="n">new_others</span>
        <span class="k">return</span> <span class="n">cluster</span></div></div>


<div class="viewcode-block" id="IStructure"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure">[docs]</a><span class="k">class</span> <span class="nc">IStructure</span><span class="p">(</span><span class="n">SiteCollection</span><span class="p">,</span> <span class="n">MSONable</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Basic immutable Structure object with periodicity. Essentially a sequence</span>
<span class="sd">    of PeriodicSites having a common lattice. IStructure is made to be</span>
<span class="sd">    (somewhat) immutable so that they can function as keys in a dict. To make</span>
<span class="sd">    modifications, use the standard Structure object instead. Structure</span>
<span class="sd">    extends Sequence and Hashable, which means that in many cases,</span>
<span class="sd">    it can be used like any Python sequence. Iterating through a</span>
<span class="sd">    structure is equivalent to going through the sites in sequence.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
                 <span class="n">lattice</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="n">List</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">],</span>
                 <span class="n">species</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">,</span> <span class="n">Composition</span><span class="p">]],</span>
                 <span class="n">coords</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">float</span><span class="p">]],</span>
                 <span class="n">charge</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="n">validate_proximity</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">to_unit_cell</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">coords_are_cartesian</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">site_properties</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Create a periodic structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            lattice (Lattice/3x3 array): The lattice, either as a</span>
<span class="sd">                :class:`pymatgen.core.lattice.Lattice` or</span>
<span class="sd">                simply as any 2D array. Each row should correspond to a lattice</span>
<span class="sd">                vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a</span>
<span class="sd">                lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].</span>
<span class="sd">            species ([Specie]): Sequence of species on each site. Can take in</span>
<span class="sd">                flexible input, including:</span>

<span class="sd">                i.  A sequence of element / specie specified either as string</span>
<span class="sd">                    symbols, e.g. [&quot;Li&quot;, &quot;Fe2+&quot;, &quot;P&quot;, ...] or atomic numbers,</span>
<span class="sd">                    e.g., (3, 56, ...) or actual Element or Specie objects.</span>

<span class="sd">                ii. List of dict of elements/species and occupancies, e.g.,</span>
<span class="sd">                    [{&quot;Fe&quot; : 0.5, &quot;Mn&quot;:0.5}, ...]. This allows the setup of</span>
<span class="sd">                    disordered structures.</span>
<span class="sd">            coords (Nx3 array): list of fractional/cartesian coordinates of</span>
<span class="sd">                each species.</span>
<span class="sd">            charge (int): overall charge of the structure. Defaults to behavior</span>
<span class="sd">                in SiteCollection where total charge is the sum of the oxidation</span>
<span class="sd">                states.</span>
<span class="sd">            validate_proximity (bool): Whether to check if there are sites</span>
<span class="sd">                that are less than 0.01 Ang apart. Defaults to False.</span>
<span class="sd">            to_unit_cell (bool): Whether to map all sites into the unit cell,</span>
<span class="sd">                i.e., fractional coords between 0 and 1. Defaults to False.</span>
<span class="sd">            coords_are_cartesian (bool): Set to True if you are providing</span>
<span class="sd">                coordinates in cartesian coordinates. Defaults to False.</span>
<span class="sd">            site_properties (dict): Properties associated with the sites as a</span>
<span class="sd">                dict of sequences, e.g., {&quot;magmom&quot;:[5,5,5,5]}. The sequences</span>
<span class="sd">                have to be the same length as the atomic species and</span>
<span class="sd">                fractional_coords. Defaults to None for no properties.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">):</span>
            <span class="k">raise</span> <span class="n">StructureError</span><span class="p">(</span><span class="s2">&quot;The list of atomic species must be of the&quot;</span>
                                 <span class="s2">&quot; same length as the list of fractional&quot;</span>
                                 <span class="s2">&quot; coordinates.&quot;</span><span class="p">)</span>

        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">lattice</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">lattice</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">lattice</span><span class="p">)</span>

        <span class="n">sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">sp</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">species</span><span class="p">):</span>
            <span class="n">prop</span> <span class="o">=</span> <span class="kc">None</span>
            <span class="k">if</span> <span class="n">site_properties</span><span class="p">:</span>
                <span class="n">prop</span> <span class="o">=</span> <span class="p">{</span><span class="n">k</span><span class="p">:</span> <span class="n">v</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
                        <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">site_properties</span><span class="o">.</span><span class="n">items</span><span class="p">()}</span>

            <span class="n">sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span>
                <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="n">coords</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                             <span class="n">to_unit_cell</span><span class="p">,</span>
                             <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="n">coords_are_cartesian</span><span class="p">,</span>
                             <span class="n">properties</span><span class="o">=</span><span class="n">prop</span><span class="p">))</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">validate_proximity</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">is_valid</span><span class="p">():</span>
            <span class="k">raise</span> <span class="n">StructureError</span><span class="p">((</span><span class="s2">&quot;Structure contains sites that are &quot;</span><span class="p">,</span>
                                  <span class="s2">&quot;less than 0.01 Angstrom apart!&quot;</span><span class="p">))</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">=</span> <span class="n">charge</span>

<div class="viewcode-block" id="IStructure.from_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.from_sites">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_sites</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span>
                   <span class="n">sites</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicSite</span><span class="p">],</span>
                   <span class="n">charge</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                   <span class="n">validate_proximity</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                   <span class="n">to_unit_cell</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Convenience constructor to make a Structure from a list of sites.</span>

<span class="sd">        Args:</span>
<span class="sd">            sites: Sequence of PeriodicSites. Sites must have the same</span>
<span class="sd">                lattice.</span>
<span class="sd">            charge: Charge of structure.</span>
<span class="sd">            validate_proximity (bool): Whether to check if there are sites</span>
<span class="sd">                that are less than 0.01 Ang apart. Defaults to False.</span>
<span class="sd">            to_unit_cell (bool): Whether to translate sites into the unit</span>
<span class="sd">                cell.</span>

<span class="sd">        Returns:</span>
<span class="sd">            (Structure) Note that missing properties are set as None.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;You need at least one site to construct a </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span>
                             <span class="bp">cls</span><span class="p">)</span>
        <span class="n">prop_keys</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[str]</span>
        <span class="n">props</span> <span class="o">=</span> <span class="p">{}</span>
        <span class="n">lattice</span> <span class="o">=</span> <span class="n">sites</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">lattice</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">sites</span><span class="p">):</span>
            <span class="k">if</span> <span class="n">site</span><span class="o">.</span><span class="n">lattice</span> <span class="o">!=</span> <span class="n">lattice</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Sites must belong to the same lattice&quot;</span><span class="p">)</span>
            <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="k">if</span> <span class="n">k</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">prop_keys</span><span class="p">:</span>
                    <span class="n">prop_keys</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">k</span><span class="p">)</span>
                    <span class="n">props</span><span class="p">[</span><span class="n">k</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="kc">None</span><span class="p">]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span>
                <span class="n">props</span><span class="p">[</span><span class="n">k</span><span class="p">][</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">v</span>
        <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">props</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
            <span class="k">if</span> <span class="nb">any</span><span class="p">((</span><span class="n">vv</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">for</span> <span class="n">vv</span> <span class="ow">in</span> <span class="n">v</span><span class="p">)):</span>
                <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;Not all sites have property </span><span class="si">%s</span><span class="s2">. Missing values &quot;</span>
                              <span class="s2">&quot;are set to None.&quot;</span> <span class="o">%</span> <span class="n">k</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">lattice</span><span class="p">,</span> <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">],</span>
                   <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">],</span>
                   <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">,</span>
                   <span class="n">site_properties</span><span class="o">=</span><span class="n">props</span><span class="p">,</span>
                   <span class="n">validate_proximity</span><span class="o">=</span><span class="n">validate_proximity</span><span class="p">,</span>
                   <span class="n">to_unit_cell</span><span class="o">=</span><span class="n">to_unit_cell</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.from_spacegroup"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.from_spacegroup">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_spacegroup</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span>
                        <span class="n">sg</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
                        <span class="n">lattice</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="n">List</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">],</span>
                        <span class="n">species</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">,</span> <span class="n">Composition</span><span class="p">]],</span>
                        <span class="n">coords</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">float</span><span class="p">]],</span>
                        <span class="n">site_properties</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                        <span class="n">coords_are_cartesian</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                        <span class="n">tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">1e-5</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Generate a structure using a spacegroup. Note that only symmetrically</span>
<span class="sd">        distinct species and coords should be provided. All equivalent sites</span>
<span class="sd">        are generated from the spacegroup operations.</span>

<span class="sd">        Args:</span>
<span class="sd">            sg (str/int): The spacegroup. If a string, it will be interpreted</span>
<span class="sd">                as one of the notations supported by</span>
<span class="sd">                pymatgen.symmetry.groups.Spacegroup. E.g., &quot;R-3c&quot; or &quot;Fm-3m&quot;.</span>
<span class="sd">                If an int, it will be interpreted as an international number.</span>
<span class="sd">            lattice (Lattice/3x3 array): The lattice, either as a</span>
<span class="sd">                :class:`pymatgen.core.lattice.Lattice` or</span>
<span class="sd">                simply as any 2D array. Each row should correspond to a lattice</span>
<span class="sd">                vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a</span>
<span class="sd">                lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].</span>
<span class="sd">                Note that no attempt is made to check that the lattice is</span>
<span class="sd">                compatible with the spacegroup specified. This may be</span>
<span class="sd">                introduced in a future version.</span>
<span class="sd">            species ([Specie]): Sequence of species on each site. Can take in</span>
<span class="sd">                flexible input, including:</span>

<span class="sd">                i.  A sequence of element / specie specified either as string</span>
<span class="sd">                    symbols, e.g. [&quot;Li&quot;, &quot;Fe2+&quot;, &quot;P&quot;, ...] or atomic numbers,</span>
<span class="sd">                    e.g., (3, 56, ...) or actual Element or Specie objects.</span>

<span class="sd">                ii. List of dict of elements/species and occupancies, e.g.,</span>
<span class="sd">                    [{&quot;Fe&quot; : 0.5, &quot;Mn&quot;:0.5}, ...]. This allows the setup of</span>
<span class="sd">                    disordered structures.</span>
<span class="sd">            coords (Nx3 array): list of fractional/cartesian coordinates of</span>
<span class="sd">                each species.</span>
<span class="sd">            coords_are_cartesian (bool): Set to True if you are providing</span>
<span class="sd">                coordinates in cartesian coordinates. Defaults to False.</span>
<span class="sd">            site_properties (dict): Properties associated with the sites as a</span>
<span class="sd">                dict of sequences, e.g., {&quot;magmom&quot;:[5,5,5,5]}. The sequences</span>
<span class="sd">                have to be the same length as the atomic species and</span>
<span class="sd">                fractional_coords. Defaults to None for no properties.</span>
<span class="sd">            tol (float): A fractional tolerance to deal with numerical</span>
<span class="sd">               precision issues in determining if orbits are the same.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="kn">from</span> <span class="nn">pymatgen.symmetry.groups</span> <span class="kn">import</span> <span class="n">SpaceGroup</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="n">i</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">sg</span><span class="p">)</span>
            <span class="n">sgp</span> <span class="o">=</span> <span class="n">SpaceGroup</span><span class="o">.</span><span class="n">from_int_number</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>
        <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
            <span class="n">sgp</span> <span class="o">=</span> <span class="n">SpaceGroup</span><span class="p">(</span><span class="n">sg</span><span class="p">)</span>

        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">lattice</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">):</span>
            <span class="n">latt</span> <span class="o">=</span> <span class="n">lattice</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">latt</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">lattice</span><span class="p">)</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="n">sgp</span><span class="o">.</span><span class="n">is_compatible</span><span class="p">(</span><span class="n">latt</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                <span class="s2">&quot;Supplied lattice with parameters </span><span class="si">%s</span><span class="s2"> is incompatible with &quot;</span>
                <span class="s2">&quot;supplied spacegroup </span><span class="si">%s</span><span class="s2">!&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">latt</span><span class="o">.</span><span class="n">parameters</span><span class="p">,</span> <span class="n">sgp</span><span class="o">.</span><span class="n">symbol</span><span class="p">)</span>
            <span class="p">)</span>

        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                <span class="s2">&quot;Supplied species and coords lengths (</span><span class="si">%d</span><span class="s2"> vs </span><span class="si">%d</span><span class="s2">) are &quot;</span>
                <span class="s2">&quot;different!&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">),</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">))</span>
            <span class="p">)</span>

        <span class="n">frac_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">coords</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">float</span><span class="p">)</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">coords_are_cartesian</span> <span class="k">else</span> \
            <span class="n">latt</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>

        <span class="n">props</span> <span class="o">=</span> <span class="p">{}</span> <span class="k">if</span> <span class="n">site_properties</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">site_properties</span>

        <span class="n">all_sp</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[Union[str, Element, Specie, DummySpecie, Composition]]</span>
        <span class="n">all_coords</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[List[float]]</span>
        <span class="n">all_site_properties</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>  <span class="c1"># type: Dict[str, List]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="n">c</span><span class="p">)</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="nb">zip</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">frac_coords</span><span class="p">)):</span>
            <span class="n">cc</span> <span class="o">=</span> <span class="n">sgp</span><span class="o">.</span><span class="n">get_orbit</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="n">tol</span><span class="p">)</span>
            <span class="n">all_sp</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">sp</span><span class="p">]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">cc</span><span class="p">))</span>
            <span class="n">all_coords</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">cc</span><span class="p">)</span>
            <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">props</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">all_site_properties</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">v</span><span class="p">[</span><span class="n">i</span><span class="p">]]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">cc</span><span class="p">))</span>

        <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">latt</span><span class="p">,</span> <span class="n">all_sp</span><span class="p">,</span> <span class="n">all_coords</span><span class="p">,</span>
                   <span class="n">site_properties</span><span class="o">=</span><span class="n">all_site_properties</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.from_magnetic_spacegroup"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.from_magnetic_spacegroup">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_magnetic_spacegroup</span><span class="p">(</span>
            <span class="bp">cls</span><span class="p">,</span>
            <span class="n">msg</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="s1">&#39;MagneticSpaceGroup&#39;</span><span class="p">],</span>  <span class="c1"># type: ignore  # noqa: F821</span>
            <span class="n">lattice</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="n">List</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">],</span>
            <span class="n">species</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">,</span> <span class="n">Composition</span><span class="p">]],</span>
            <span class="n">coords</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">float</span><span class="p">]],</span>
            <span class="n">site_properties</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Sequence</span><span class="p">],</span>
            <span class="n">coords_are_cartesian</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
            <span class="n">tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">1e-5</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Generate a structure using a magnetic spacegroup. Note that only</span>
<span class="sd">        symmetrically distinct species, coords and magmoms should be provided.]</span>
<span class="sd">        All equivalent sites are generated from the spacegroup operations.</span>

<span class="sd">        Args:</span>
<span class="sd">            msg (str/list/:class:`pymatgen.symmetry.maggroups.MagneticSpaceGroup`):</span>
<span class="sd">                The magnetic spacegroup.</span>
<span class="sd">                If a string, it will be interpreted as one of the notations</span>
<span class="sd">                supported by MagneticSymmetryGroup, e.g., &quot;R-3&#39;c&quot; or &quot;Fm&#39;-3&#39;m&quot;.</span>
<span class="sd">                If a list of two ints, it will be interpreted as the number of</span>
<span class="sd">                the spacegroup in its Belov, Neronova and Smirnova (BNS) setting.</span>
<span class="sd">            lattice (Lattice/3x3 array): The lattice, either as a</span>
<span class="sd">                :class:`pymatgen.core.lattice.Lattice` or</span>
<span class="sd">                simply as any 2D array. Each row should correspond to a lattice</span>
<span class="sd">                vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a</span>
<span class="sd">                lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].</span>
<span class="sd">                Note that no attempt is made to check that the lattice is</span>
<span class="sd">                compatible with the spacegroup specified. This may be</span>
<span class="sd">                introduced in a future version.</span>
<span class="sd">            species ([Specie]): Sequence of species on each site. Can take in</span>
<span class="sd">                flexible input, including:</span>
<span class="sd">                i.  A sequence of element / specie specified either as string</span>
<span class="sd">                symbols, e.g. [&quot;Li&quot;, &quot;Fe2+&quot;, &quot;P&quot;, ...] or atomic numbers,</span>
<span class="sd">                e.g., (3, 56, ...) or actual Element or Specie objects.</span>

<span class="sd">                ii. List of dict of elements/species and occupancies, e.g.,</span>
<span class="sd">                    [{&quot;Fe&quot; : 0.5, &quot;Mn&quot;:0.5}, ...]. This allows the setup of</span>
<span class="sd">                    disordered structures.</span>
<span class="sd">            coords (Nx3 array): list of fractional/cartesian coordinates of</span>
<span class="sd">                each species.</span>
<span class="sd">            site_properties (dict): Properties associated with the sites as a</span>
<span class="sd">                dict of sequences, e.g., {&quot;magmom&quot;:[5,5,5,5]}. The sequences</span>
<span class="sd">                have to be the same length as the atomic species and</span>
<span class="sd">                fractional_coords. Unlike Structure.from_spacegroup(),</span>
<span class="sd">                this argument is mandatory, since magnetic moment information</span>
<span class="sd">                has to be included. Note that the *direction* of the supplied</span>
<span class="sd">                magnetic moment relative to the crystal is important, even if</span>
<span class="sd">                the resulting structure is used for collinear calculations.</span>
<span class="sd">            coords_are_cartesian (bool): Set to True if you are providing</span>
<span class="sd">                coordinates in cartesian coordinates. Defaults to False.</span>
<span class="sd">            tol (float): A fractional tolerance to deal with numerical</span>
<span class="sd">                precision issues in determining if orbits are the same.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="kn">from</span> <span class="nn">pymatgen.electronic_structure.core</span> <span class="kn">import</span> <span class="n">Magmom</span>
        <span class="kn">from</span> <span class="nn">pymatgen.symmetry.maggroups</span> <span class="kn">import</span> <span class="n">MagneticSpaceGroup</span>

        <span class="k">if</span> <span class="s1">&#39;magmom&#39;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">site_properties</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;Magnetic moments have to be defined.&#39;</span><span class="p">)</span>

        <span class="n">magmoms</span> <span class="o">=</span> <span class="p">[</span><span class="n">Magmom</span><span class="p">(</span><span class="n">m</span><span class="p">)</span> <span class="k">for</span> <span class="n">m</span> <span class="ow">in</span> <span class="n">site_properties</span><span class="p">[</span><span class="s1">&#39;magmom&#39;</span><span class="p">]]</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="n">MagneticSpaceGroup</span><span class="p">):</span>
            <span class="n">msg</span> <span class="o">=</span> <span class="n">MagneticSpaceGroup</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>  <span class="c1"># type: ignore</span>

        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">lattice</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">):</span>
            <span class="n">latt</span> <span class="o">=</span> <span class="n">lattice</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">latt</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">lattice</span><span class="p">)</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="n">msg</span><span class="o">.</span><span class="n">is_compatible</span><span class="p">(</span><span class="n">latt</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                <span class="s2">&quot;Supplied lattice with parameters </span><span class="si">%s</span><span class="s2"> is incompatible with &quot;</span>
                <span class="s2">&quot;supplied spacegroup </span><span class="si">%s</span><span class="s2">!&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">latt</span><span class="o">.</span><span class="n">parameters</span><span class="p">,</span> <span class="n">msg</span><span class="o">.</span><span class="n">sg_symbol</span><span class="p">)</span>
            <span class="p">)</span>

        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                <span class="s2">&quot;Supplied species and coords lengths (</span><span class="si">%d</span><span class="s2"> vs </span><span class="si">%d</span><span class="s2">) are &quot;</span>
                <span class="s2">&quot;different!&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">),</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">))</span>
            <span class="p">)</span>

        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">magmoms</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                <span class="s2">&quot;Supplied species and magmom lengths (</span><span class="si">%d</span><span class="s2"> vs </span><span class="si">%d</span><span class="s2">) are &quot;</span>
                <span class="s2">&quot;different!&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">),</span> <span class="nb">len</span><span class="p">(</span><span class="n">magmoms</span><span class="p">))</span>
            <span class="p">)</span>

        <span class="n">frac_coords</span> <span class="o">=</span> <span class="n">coords</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">coords_are_cartesian</span> <span class="k">else</span> <span class="n">latt</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>

        <span class="n">all_sp</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[Union[str, Element, Specie, DummySpecie, Composition]]</span>
        <span class="n">all_coords</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[List[float]]</span>
        <span class="n">all_magmoms</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[float]</span>
        <span class="n">all_site_properties</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>  <span class="c1"># type: Dict[str, List]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">m</span><span class="p">)</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="nb">zip</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">frac_coords</span><span class="p">,</span> <span class="n">magmoms</span><span class="p">)):</span>
            <span class="n">cc</span><span class="p">,</span> <span class="n">mm</span> <span class="o">=</span> <span class="n">msg</span><span class="o">.</span><span class="n">get_orbit</span><span class="p">(</span><span class="n">c</span><span class="p">,</span> <span class="n">m</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="n">tol</span><span class="p">)</span>
            <span class="n">all_sp</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">sp</span><span class="p">]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">cc</span><span class="p">))</span>
            <span class="n">all_coords</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">cc</span><span class="p">)</span>
            <span class="n">all_magmoms</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">mm</span><span class="p">)</span>
            <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">site_properties</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="k">if</span> <span class="n">k</span> <span class="o">!=</span> <span class="s1">&#39;magmom&#39;</span><span class="p">:</span>
                    <span class="n">all_site_properties</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">v</span><span class="p">[</span><span class="n">i</span><span class="p">]]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">cc</span><span class="p">))</span>

        <span class="n">all_site_properties</span><span class="p">[</span><span class="s1">&#39;magmom&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">all_magmoms</span>

        <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">latt</span><span class="p">,</span> <span class="n">all_sp</span><span class="p">,</span> <span class="n">all_coords</span><span class="p">,</span>
                   <span class="n">site_properties</span><span class="o">=</span><span class="n">all_site_properties</span><span class="p">)</span></div>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">charge</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Overall charge of the structure</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="k">return</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">charge</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">distance_matrix</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns the distance matrix between all sites in the structure. For</span>
<span class="sd">        periodic structures, this should return the nearest image distance.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">get_all_distances</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span>
                                              <span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">sites</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns an iterator for the sites in the Structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">lattice</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Lattice of the structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">density</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns the density in units of g/cc</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">m</span> <span class="o">=</span> <span class="n">Mass</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">weight</span><span class="p">,</span> <span class="s2">&quot;amu&quot;</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">m</span><span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="s2">&quot;g&quot;</span><span class="p">)</span> <span class="o">/</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">volume</span> <span class="o">*</span> <span class="n">Length</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;ang&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">to</span><span class="p">(</span><span class="s2">&quot;cm&quot;</span><span class="p">)</span> <span class="o">**</span> <span class="mi">3</span><span class="p">)</span>

<div class="viewcode-block" id="IStructure.get_space_group_info"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_space_group_info">[docs]</a>    <span class="k">def</span> <span class="nf">get_space_group_info</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">symprec</span><span class="o">=</span><span class="mf">1e-2</span><span class="p">,</span> <span class="n">angle_tolerance</span><span class="o">=</span><span class="mf">5.0</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Convenience method to quickly get the spacegroup of a structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            symprec (float): Same definition as in SpacegroupAnalyzer.</span>
<span class="sd">                Defaults to 1e-2.</span>
<span class="sd">            angle_tolerance (float): Same definition as in SpacegroupAnalyzer.</span>
<span class="sd">                Defaults to 5 degrees.</span>

<span class="sd">        Returns:</span>
<span class="sd">            spacegroup_symbol, international_number</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="c1"># Import within method needed to avoid cyclic dependency.</span>
        <span class="kn">from</span> <span class="nn">pymatgen.symmetry.analyzer</span> <span class="kn">import</span> <span class="n">SpacegroupAnalyzer</span>
        <span class="n">a</span> <span class="o">=</span> <span class="n">SpacegroupAnalyzer</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">symprec</span><span class="o">=</span><span class="n">symprec</span><span class="p">,</span>
                               <span class="n">angle_tolerance</span><span class="o">=</span><span class="n">angle_tolerance</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">a</span><span class="o">.</span><span class="n">get_space_group_symbol</span><span class="p">(),</span> <span class="n">a</span><span class="o">.</span><span class="n">get_space_group_number</span><span class="p">()</span></div>

<div class="viewcode-block" id="IStructure.matches"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.matches">[docs]</a>    <span class="k">def</span> <span class="nf">matches</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">,</span> <span class="n">anonymous</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Check whether this structure is similar to another structure.</span>
<span class="sd">        Basically a convenience method to call structure matching.</span>

<span class="sd">        Args:</span>
<span class="sd">            other (IStructure/Structure): Another structure.</span>
<span class="sd">            **kwargs: Same **kwargs as in</span>
<span class="sd">                :class:`pymatgen.analysis.structure_matcher.StructureMatcher`.</span>

<span class="sd">        Returns:</span>
<span class="sd">            (bool) True is the structures are similar under some affine</span>
<span class="sd">            transformation.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="kn">from</span> <span class="nn">pymatgen.analysis.structure_matcher</span> <span class="kn">import</span> <span class="n">StructureMatcher</span>
        <span class="n">m</span> <span class="o">=</span> <span class="n">StructureMatcher</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">anonymous</span><span class="p">:</span>
            <span class="k">return</span> <span class="n">m</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">m</span><span class="o">.</span><span class="n">fit_anonymous</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">)</span></div>

    <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">other</span> <span class="ow">is</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">True</span>
        <span class="k">if</span> <span class="n">other</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">other</span><span class="p">):</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span> <span class="o">!=</span> <span class="n">other</span><span class="o">.</span><span class="n">lattice</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">site</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">other</span><span class="p">:</span>
                <span class="k">return</span> <span class="kc">False</span>
        <span class="k">return</span> <span class="kc">True</span>

    <span class="k">def</span> <span class="fm">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">return</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__eq__</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__hash__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># For now, just use the composition hash code.</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">()</span>

    <span class="k">def</span> <span class="fm">__mul__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">scaling_matrix</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Makes a supercell. Allowing to have sites outside the unit cell</span>

<span class="sd">        Args:</span>
<span class="sd">            scaling_matrix: A scaling matrix for transforming the lattice</span>
<span class="sd">                vectors. Has to be all integers. Several options are possible:</span>

<span class="sd">                a. A full 3x3 scaling matrix defining the linear combination</span>
<span class="sd">                   the old lattice vectors. E.g., [[2,1,0],[0,3,0],[0,0,</span>
<span class="sd">                   1]] generates a new structure with lattice vectors a&#39; =</span>
<span class="sd">                   2a + b, b&#39; = 3b, c&#39; = c where a, b, and c are the lattice</span>
<span class="sd">                   vectors of the original structure.</span>
<span class="sd">                b. An sequence of three scaling factors. E.g., [2, 1, 1]</span>
<span class="sd">                   specifies that the supercell should have dimensions 2a x b x</span>
<span class="sd">                   c.</span>
<span class="sd">                c. A number, which simply scales all lattice vectors by the</span>
<span class="sd">                   same factor.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Supercell structure. Note that a Structure is always returned,</span>
<span class="sd">            even if the input structure is a subclass of Structure. This is</span>
<span class="sd">            to avoid different arguments signatures from causing problems. If</span>
<span class="sd">            you prefer a subclass to return its own type, you need to override</span>
<span class="sd">            this method in the subclass.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">scale_matrix</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">scaling_matrix</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">int16</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">scale_matrix</span><span class="o">.</span><span class="n">shape</span> <span class="o">!=</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">3</span><span class="p">):</span>
            <span class="n">scale_matrix</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">scale_matrix</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">eye</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">np</span><span class="o">.</span><span class="n">int16</span><span class="p">)</span>
        <span class="n">new_lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">scale_matrix</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">matrix</span><span class="p">))</span>

        <span class="n">f_lat</span> <span class="o">=</span> <span class="n">lattice_points_in_supercell</span><span class="p">(</span><span class="n">scale_matrix</span><span class="p">)</span>
        <span class="n">c_lat</span> <span class="o">=</span> <span class="n">new_lattice</span><span class="o">.</span><span class="n">get_cartesian_coords</span><span class="p">(</span><span class="n">f_lat</span><span class="p">)</span>

        <span class="n">new_sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">c_lat</span><span class="p">:</span>
                <span class="n">s</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span>
                    <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="o">+</span> <span class="n">v</span><span class="p">,</span>
                    <span class="n">new_lattice</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                    <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">to_unit_cell</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
                    <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
                <span class="n">new_sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>

        <span class="n">new_charge</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">det</span><span class="p">(</span><span class="n">scale_matrix</span><span class="p">)</span> <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="k">else</span> <span class="kc">None</span>
        <span class="k">return</span> <span class="n">Structure</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">new_sites</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="n">new_charge</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__rmul__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">scaling_matrix</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Similar to __mul__ to preserve commutativeness.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__mul__</span><span class="p">(</span><span class="n">scaling_matrix</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">frac_coords</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Fractional coordinates as a Nx3 numpy array.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">])</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">volume</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns the volume of the structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">volume</span>

<div class="viewcode-block" id="IStructure.get_distance"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_distance">[docs]</a>    <span class="k">def</span> <span class="nf">get_distance</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">jimage</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get distance between site i and j assuming periodic boundary</span>
<span class="sd">        conditions. If the index jimage of two sites atom j is not specified it</span>
<span class="sd">        selects the jimage nearest to the i atom and returns the distance and</span>
<span class="sd">        jimage indices in terms of lattice vector translations if the index</span>
<span class="sd">        jimage of atom j is specified it returns the distance between the i</span>
<span class="sd">        atom and the specified jimage atom.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int): Index of first site</span>
<span class="sd">            j (int): Index of second site</span>
<span class="sd">            jimage: Number of lattice translations in each lattice direction.</span>
<span class="sd">                Default is None for nearest image.</span>

<span class="sd">        Returns:</span>
<span class="sd">            distance</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">distance</span><span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">],</span> <span class="n">jimage</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.get_sites_in_sphere"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_sites_in_sphere">[docs]</a>    <span class="k">def</span> <span class="nf">get_sites_in_sphere</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pt</span><span class="p">:</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">,</span> <span class="n">r</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
                            <span class="n">include_index</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                            <span class="n">include_image</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">)</span> \
            <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">Tuple</span><span class="p">[</span><span class="n">PeriodicSite</span><span class="p">,</span> <span class="nb">float</span><span class="p">,</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">int</span><span class="p">],</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Tuple</span><span class="p">[</span><span class="nb">int</span><span class="p">]]]]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Find all sites within a sphere from the point, including a site (if any)</span>
<span class="sd">        sitting on the point itself. This includes sites in other periodic</span>
<span class="sd">        images.</span>

<span class="sd">        Algorithm:</span>

<span class="sd">        1. place sphere of radius r in crystal and determine minimum supercell</span>
<span class="sd">           (parallelpiped) which would contain a sphere of radius r. for this</span>
<span class="sd">           we need the projection of a_1 on a unit vector perpendicular</span>
<span class="sd">           to a_2 &amp; a_3 (i.e. the unit vector in the direction b_1) to</span>
<span class="sd">           determine how many a_1&quot;s it will take to contain the sphere.</span>

<span class="sd">           Nxmax = r * length_of_b_1 / (2 Pi)</span>

<span class="sd">        2. keep points falling within r.</span>

<span class="sd">        Args:</span>
<span class="sd">            pt (3x1 array): cartesian coordinates of center of sphere.</span>
<span class="sd">            r (float): Radius of sphere.</span>
<span class="sd">            include_index (bool): Whether the non-supercell site index</span>
<span class="sd">                is included in the returned data</span>
<span class="sd">            include_image (bool): Whether to include the supercell image</span>
<span class="sd">                is included in the returned data</span>

<span class="sd">        Returns:</span>
<span class="sd">            [(site, dist) ...] since most of the time, subsequent processing</span>
<span class="sd">            requires the distance.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">site_fcoords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">mod</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
        <span class="n">neighbors</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># type: List[Tuple[PeriodicSite, float, Optional[int], Optional[Tuple[int]]]]</span>
        <span class="k">for</span> <span class="n">fcoord</span><span class="p">,</span> <span class="n">dist</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">img</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_points_in_sphere</span><span class="p">(</span>
                <span class="n">site_fcoords</span><span class="p">,</span> <span class="n">pt</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
            <span class="n">nnsite</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">species</span><span class="p">,</span>
                                  <span class="n">fcoord</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                  <span class="n">properties</span><span class="o">=</span><span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                                  <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

            <span class="c1"># Get the neighbor data</span>
            <span class="n">nn_data</span> <span class="o">=</span> <span class="p">(</span><span class="n">nnsite</span><span class="p">,</span> <span class="n">dist</span><span class="p">)</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">include_index</span> <span class="k">else</span> <span class="p">(</span><span class="n">nnsite</span><span class="p">,</span> <span class="n">dist</span><span class="p">,</span> <span class="n">i</span><span class="p">)</span>  <span class="c1"># type: ignore</span>
            <span class="k">if</span> <span class="n">include_image</span><span class="p">:</span>
                <span class="n">nn_data</span> <span class="o">+=</span> <span class="p">(</span><span class="n">img</span><span class="p">,</span> <span class="p">)</span>  <span class="c1"># type: ignore</span>
            <span class="n">neighbors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">nn_data</span><span class="p">)</span>  <span class="c1"># type: ignore</span>
        <span class="k">return</span> <span class="n">neighbors</span></div>

<div class="viewcode-block" id="IStructure.get_neighbors"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_neighbors">[docs]</a>    <span class="k">def</span> <span class="nf">get_neighbors</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">site</span><span class="p">:</span> <span class="n">PeriodicSite</span><span class="p">,</span> <span class="n">r</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
                      <span class="n">include_index</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">include_image</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">)</span> \
            <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicNeighbor</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get all neighbors to a site within a sphere of radius r.  Excludes the</span>
<span class="sd">        site itself.</span>

<span class="sd">        Args:</span>
<span class="sd">            site (Site): Which is the center of the sphere.</span>
<span class="sd">            r (float): Radius of sphere.</span>
<span class="sd">            include_index (bool): Deprecated. Now, the non-supercell site index</span>
<span class="sd">                is always included in the returned data.</span>
<span class="sd">            include_image (bool): Deprecated. Now the supercell image</span>
<span class="sd">                is always included in the returned data.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [PeriodicNeighbor] where PeriodicNeighbor is a namedtuple containing</span>
<span class="sd">            (site, distance, index, image).</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_all_neighbors</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="n">include_index</span><span class="o">=</span><span class="n">include_index</span><span class="p">,</span>
                                      <span class="n">include_image</span><span class="o">=</span><span class="n">include_image</span><span class="p">,</span>
                                      <span class="n">sites</span><span class="o">=</span><span class="p">[</span><span class="n">site</span><span class="p">])[</span><span class="mi">0</span><span class="p">]</span></div>

    <span class="nd">@deprecated</span><span class="p">(</span><span class="n">get_neighbors</span><span class="p">,</span> <span class="s2">&quot;This is retained purely for checking purposes.&quot;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">get_neighbors_old</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">site</span><span class="p">,</span> <span class="n">r</span><span class="p">,</span> <span class="n">include_index</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">include_image</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get all neighbors to a site within a sphere of radius r.  Excludes the</span>
<span class="sd">        site itself.</span>

<span class="sd">        Args:</span>
<span class="sd">            site (Site): Which is the center of the sphere.</span>
<span class="sd">            r (float): Radius of sphere.</span>
<span class="sd">            include_index (bool): Whether the non-supercell site index</span>
<span class="sd">                is included in the returned data</span>
<span class="sd">            include_image (bool): Whether to include the supercell image</span>
<span class="sd">                is included in the returned data</span>

<span class="sd">        Returns:</span>
<span class="sd">            [PeriodicNeighbor] where PeriodicNeighbor is a namedtuple containing</span>
<span class="sd">            (site, distance, index, image).</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">nn</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_sites_in_sphere</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span> <span class="n">r</span><span class="p">,</span>
                                      <span class="n">include_index</span><span class="o">=</span><span class="n">include_index</span><span class="p">,</span>
                                      <span class="n">include_image</span><span class="o">=</span><span class="n">include_image</span><span class="p">)</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">d</span> <span class="k">for</span> <span class="n">d</span> <span class="ow">in</span> <span class="n">nn</span> <span class="k">if</span> <span class="n">site</span> <span class="o">!=</span> <span class="n">d</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span>

    <span class="k">def</span> <span class="nf">_get_neighbor_list_py</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
                              <span class="n">sites</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicSite</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                              <span class="n">numerical_tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">1e-8</span><span class="p">,</span>
                              <span class="n">exclude_self</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span> <span class="o">...</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        A python version of getting neighbor_list. The returned values are a tuple of</span>
<span class="sd">        numpy arrays (center_indices, points_indices, offset_vectors, distances).</span>
<span class="sd">        Atom `center_indices[i]` has neighbor atom `points_indices[i]` that is</span>
<span class="sd">        translated by `offset_vectors[i]` lattice vectors, and the distance is</span>
<span class="sd">        `distances[i]`.</span>

<span class="sd">        Args:</span>
<span class="sd">            r (float): Radius of sphere</span>
<span class="sd">            sites (list of Sites or None): sites for getting all neighbors,</span>
<span class="sd">                default is None, which means neighbors will be obtained for all</span>
<span class="sd">                sites. This is useful in the situation where you are interested</span>
<span class="sd">                only in one subspecies type, and makes it a lot faster.</span>
<span class="sd">            numerical_tol (float): This is a numerical tolerance for distances.</span>
<span class="sd">                Sites which are &lt; numerical_tol are determined to be conincident</span>
<span class="sd">                with the site. Sites which are r + numerical_tol away is deemed</span>
<span class="sd">                to be within r from the site. The default of 1e-8 should be</span>
<span class="sd">                ok in most instances.</span>
<span class="sd">            exclude_self (bool): whether to exclude atom neighboring with itself within</span>
<span class="sd">                numerical tolerance distance, default to True</span>
<span class="sd">        Returns: (center_indices, points_indices, offset_vectors, distances)</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">neighbors</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_all_neighbors_py</span><span class="p">(</span><span class="n">r</span><span class="o">=</span><span class="n">r</span><span class="p">,</span> <span class="n">include_index</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">include_image</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                                              <span class="n">sites</span><span class="o">=</span><span class="n">sites</span><span class="p">,</span> <span class="n">numerical_tol</span><span class="o">=</span><span class="mf">1e-8</span><span class="p">)</span>
        <span class="n">center_indices</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">points_indices</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">offsets</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">distances</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">nns</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">neighbors</span><span class="p">):</span>
            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">nns</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
                <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="n">nns</span><span class="p">:</span>
                    <span class="k">if</span> <span class="n">exclude_self</span> <span class="ow">and</span> <span class="p">(</span><span class="n">i</span> <span class="o">==</span> <span class="n">n</span><span class="o">.</span><span class="n">index</span><span class="p">)</span> <span class="ow">and</span> <span class="p">(</span><span class="n">n</span><span class="o">.</span><span class="n">nn_distance</span> <span class="o">&lt;=</span> <span class="n">numerical_tol</span><span class="p">):</span>
                        <span class="k">continue</span>
                    <span class="n">center_indices</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>
                    <span class="n">points_indices</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">n</span><span class="o">.</span><span class="n">index</span><span class="p">)</span>
                    <span class="n">offsets</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">n</span><span class="o">.</span><span class="n">image</span><span class="p">)</span>
                    <span class="n">distances</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">n</span><span class="o">.</span><span class="n">nn_distance</span><span class="p">)</span>
        <span class="k">return</span> <span class="nb">tuple</span><span class="p">((</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">center_indices</span><span class="p">),</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">points_indices</span><span class="p">),</span>
                     <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">offsets</span><span class="p">),</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">distances</span><span class="p">)))</span>

<div class="viewcode-block" id="IStructure.get_neighbor_list"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_neighbor_list">[docs]</a>    <span class="k">def</span> <span class="nf">get_neighbor_list</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
                          <span class="n">sites</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicSite</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                          <span class="n">numerical_tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">1e-8</span><span class="p">,</span>
                          <span class="n">exclude_self</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Tuple</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span> <span class="o">...</span><span class="p">]:</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get neighbor lists using numpy array representations without constructing</span>
<span class="sd">        Neighbor objects. If the cython extension is installed,  this method will</span>
<span class="sd">        be orders of magnitude faster than `get_all_neighbors`.</span>
<span class="sd">        The returned values are a tuple of numpy arrays</span>
<span class="sd">        (center_indices, points_indices, offset_vectors, distances).</span>
<span class="sd">        Atom `center_indices[i]` has neighbor atom `points_indices[i]` that is</span>
<span class="sd">        translated by `offset_vectors[i]` lattice vectors, and the distance is</span>
<span class="sd">        `distances[i]`.</span>

<span class="sd">        Args:</span>
<span class="sd">            r (float): Radius of sphere</span>
<span class="sd">            sites (list of Sites or None): sites for getting all neighbors,</span>
<span class="sd">                default is None, which means neighbors will be obtained for all</span>
<span class="sd">                sites. This is useful in the situation where you are interested</span>
<span class="sd">                only in one subspecies type, and makes it a lot faster.</span>
<span class="sd">            numerical_tol (float): This is a numerical tolerance for distances.</span>
<span class="sd">                Sites which are &lt; numerical_tol are determined to be conincident</span>
<span class="sd">                with the site. Sites which are r + numerical_tol away is deemed</span>
<span class="sd">                to be within r from the site. The default of 1e-8 should be</span>
<span class="sd">                ok in most instances.</span>
<span class="sd">            exclude_self (bool): whether to exclude atom neighboring with itself within</span>
<span class="sd">                numerical tolerance distance, default to True</span>
<span class="sd">        Returns: (center_indices, points_indices, offset_vectors, distances)</span>

<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="kn">from</span> <span class="nn">pymatgen.optimization.neighbors</span> <span class="kn">import</span> <span class="n">find_points_in_spheres</span>  <span class="c1"># type: ignore</span>
        <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_get_neighbor_list_py</span><span class="p">(</span><span class="n">r</span><span class="p">,</span> <span class="n">sites</span><span class="p">,</span> <span class="n">exclude_self</span><span class="o">=</span><span class="n">exclude_self</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">sites</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
                <span class="n">sites</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span>
            <span class="n">site_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
            <span class="n">cart_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">ascontiguousarray</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">),</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
            <span class="n">lattice_matrix</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">ascontiguousarray</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">matrix</span><span class="p">),</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">float</span><span class="p">)</span>
            <span class="n">r</span> <span class="o">=</span> <span class="nb">float</span><span class="p">(</span><span class="n">r</span><span class="p">)</span>
            <span class="n">center_indices</span><span class="p">,</span> <span class="n">points_indices</span><span class="p">,</span> <span class="n">images</span><span class="p">,</span> <span class="n">distances</span> <span class="o">=</span> \
                <span class="n">find_points_in_spheres</span><span class="p">(</span><span class="n">cart_coords</span><span class="p">,</span> <span class="n">site_coords</span><span class="p">,</span> <span class="n">r</span><span class="o">=</span><span class="n">r</span><span class="p">,</span>
                                       <span class="n">pbc</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span> <span class="n">dtype</span><span class="o">=</span><span class="nb">int</span><span class="p">),</span>
                                       <span class="n">lattice</span><span class="o">=</span><span class="n">lattice_matrix</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="n">numerical_tol</span><span class="p">)</span>
            <span class="n">cond</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="kc">True</span><span class="p">]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">center_indices</span><span class="p">))</span>
            <span class="k">if</span> <span class="n">exclude_self</span><span class="p">:</span>
                <span class="n">self_pair</span> <span class="o">=</span> <span class="p">(</span><span class="n">center_indices</span> <span class="o">==</span> <span class="n">points_indices</span><span class="p">)</span> <span class="o">&amp;</span> <span class="p">(</span><span class="n">distances</span> <span class="o">&lt;=</span> <span class="n">numerical_tol</span><span class="p">)</span>
                <span class="n">cond</span> <span class="o">=</span> <span class="o">~</span><span class="n">self_pair</span>
            <span class="k">return</span> <span class="nb">tuple</span><span class="p">((</span><span class="n">center_indices</span><span class="p">[</span><span class="n">cond</span><span class="p">],</span> <span class="n">points_indices</span><span class="p">[</span><span class="n">cond</span><span class="p">],</span>
                         <span class="n">images</span><span class="p">[</span><span class="n">cond</span><span class="p">],</span> <span class="n">distances</span><span class="p">[</span><span class="n">cond</span><span class="p">]))</span></div>

<div class="viewcode-block" id="IStructure.get_all_neighbors"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_all_neighbors">[docs]</a>    <span class="k">def</span> <span class="nf">get_all_neighbors</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
                          <span class="n">include_index</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                          <span class="n">include_image</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                          <span class="n">sites</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicSite</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                          <span class="n">numerical_tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">1e-8</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">PeriodicNeighbor</span><span class="p">]]:</span>

        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get neighbors for each atom in the unit cell, out to a distance r</span>
<span class="sd">        Returns a list of list of neighbors for each site in structure.</span>
<span class="sd">        Use this method if you are planning on looping over all sites in the</span>
<span class="sd">        crystal. If you only want neighbors for a particular site, use the</span>
<span class="sd">        method get_neighbors as it may not have to build such a large supercell</span>
<span class="sd">        However if you are looping over all sites in the crystal, this method</span>
<span class="sd">        is more efficient since it only performs one pass over a large enough</span>
<span class="sd">        supercell to contain all possible atoms out to a distance r.</span>
<span class="sd">        The return type is a [(site, dist) ...] since most of the time,</span>
<span class="sd">        subsequent processing requires the distance.</span>

<span class="sd">        A note about periodic images: Before computing the neighbors, this</span>
<span class="sd">        operation translates all atoms to within the unit cell (having</span>
<span class="sd">        fractional coordinates within [0,1)). This means that the &quot;image&quot; of a</span>
<span class="sd">        site does not correspond to how much it has been translates from its</span>
<span class="sd">        current position, but which image of the unit cell it resides.</span>

<span class="sd">        Args:</span>
<span class="sd">            r (float): Radius of sphere.</span>
<span class="sd">            include_index (bool): Deprecated. Now, the non-supercell site index</span>
<span class="sd">                is always included in the returned data.</span>
<span class="sd">            include_image (bool): Deprecated. Now the supercell image</span>
<span class="sd">                is always included in the returned data.</span>
<span class="sd">            sites (list of Sites or None): sites for getting all neighbors,</span>
<span class="sd">                default is None, which means neighbors will be obtained for all</span>
<span class="sd">                sites. This is useful in the situation where you are interested</span>
<span class="sd">                only in one subspecies type, and makes it a lot faster.</span>
<span class="sd">            numerical_tol (float): This is a numerical tolerance for distances.</span>
<span class="sd">                Sites which are &lt; numerical_tol are determined to be conincident</span>
<span class="sd">                with the site. Sites which are r + numerical_tol away is deemed</span>
<span class="sd">                to be within r from the site. The default of 1e-8 should be</span>
<span class="sd">                ok in most instances.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [PeriodicNeighbor] where PeriodicNeighbor is a namedtuple containing</span>
<span class="sd">            (site, distance, index, image).</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">sites</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">sites</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span>
        <span class="n">center_indices</span><span class="p">,</span> <span class="n">points_indices</span><span class="p">,</span> <span class="n">images</span><span class="p">,</span> <span class="n">distances</span> <span class="o">=</span> \
            <span class="bp">self</span><span class="o">.</span><span class="n">get_neighbor_list</span><span class="p">(</span><span class="n">r</span><span class="o">=</span><span class="n">r</span><span class="p">,</span> <span class="n">sites</span><span class="o">=</span><span class="n">sites</span><span class="p">,</span> <span class="n">numerical_tol</span><span class="o">=</span><span class="n">numerical_tol</span><span class="p">)</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">points_indices</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>
            <span class="k">return</span> <span class="p">[[]]</span> <span class="o">*</span> <span class="nb">len</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span>
        <span class="n">f_coords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">[</span><span class="n">points_indices</span><span class="p">]</span> <span class="o">+</span> <span class="n">images</span>
        <span class="n">neighbor_dict</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="n">List</span><span class="p">]</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
        <span class="n">lattice</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span>
        <span class="n">atol</span> <span class="o">=</span> <span class="n">Site</span><span class="o">.</span><span class="n">position_atol</span>
        <span class="n">all_sites</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span>
        <span class="k">for</span> <span class="n">cindex</span><span class="p">,</span> <span class="n">pindex</span><span class="p">,</span> <span class="n">image</span><span class="p">,</span> <span class="n">f_coord</span><span class="p">,</span> <span class="n">d</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">center_indices</span><span class="p">,</span> <span class="n">points_indices</span><span class="p">,</span> <span class="n">images</span><span class="p">,</span> <span class="n">f_coords</span><span class="p">,</span> <span class="n">distances</span><span class="p">):</span>
            <span class="n">psite</span> <span class="o">=</span> <span class="n">all_sites</span><span class="p">[</span><span class="n">pindex</span><span class="p">]</span>
            <span class="n">csite</span> <span class="o">=</span> <span class="n">sites</span><span class="p">[</span><span class="n">cindex</span><span class="p">]</span>
            <span class="k">if</span> <span class="p">(</span><span class="n">d</span> <span class="o">&gt;</span> <span class="n">numerical_tol</span> <span class="ow">or</span>
                    <span class="c1"># This simply compares the psite and csite. The reason why manual comparison is done is</span>
                    <span class="c1"># for speed. This does not check the lattice since they are always equal. Also, the or construct</span>
                    <span class="c1"># returns True immediately once one of the conditions are satisfied.</span>
                    <span class="n">psite</span><span class="o">.</span><span class="n">species</span> <span class="o">!=</span> <span class="n">csite</span><span class="o">.</span><span class="n">species</span> <span class="ow">or</span>
                    <span class="p">(</span><span class="ow">not</span> <span class="n">np</span><span class="o">.</span><span class="n">allclose</span><span class="p">(</span><span class="n">psite</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span> <span class="n">csite</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span> <span class="n">atol</span><span class="o">=</span><span class="n">atol</span><span class="p">))</span> <span class="ow">or</span>
                    <span class="p">(</span><span class="ow">not</span> <span class="n">psite</span><span class="o">.</span><span class="n">properties</span> <span class="o">==</span> <span class="n">csite</span><span class="o">.</span><span class="n">properties</span><span class="p">)):</span>
                <span class="n">neighbor_dict</span><span class="p">[</span><span class="n">cindex</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">PeriodicNeighbor</span><span class="p">(</span>
                    <span class="n">species</span><span class="o">=</span><span class="n">psite</span><span class="o">.</span><span class="n">species</span><span class="p">,</span>
                    <span class="n">coords</span><span class="o">=</span><span class="n">f_coord</span><span class="p">,</span>
                    <span class="n">lattice</span><span class="o">=</span><span class="n">lattice</span><span class="p">,</span>
                    <span class="n">properties</span><span class="o">=</span><span class="n">psite</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                    <span class="n">nn_distance</span><span class="o">=</span><span class="n">d</span><span class="p">,</span>
                    <span class="n">index</span><span class="o">=</span><span class="n">pindex</span><span class="p">,</span>
                    <span class="n">image</span><span class="o">=</span><span class="nb">tuple</span><span class="p">(</span><span class="n">image</span><span class="p">)))</span>

        <span class="n">neighbors</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">PeriodicNeighbor</span><span class="p">]]</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">sites</span><span class="p">)):</span>
            <span class="n">neighbors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">neighbor_dict</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
        <span class="k">return</span> <span class="n">neighbors</span></div>

<div class="viewcode-block" id="IStructure.get_all_neighbors_py"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_all_neighbors_py">[docs]</a>    <span class="k">def</span> <span class="nf">get_all_neighbors_py</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span>
                             <span class="n">include_index</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                             <span class="n">include_image</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                             <span class="n">sites</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicSite</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                             <span class="n">numerical_tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">1e-8</span><span class="p">)</span> \
            <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">PeriodicNeighbor</span><span class="p">]]:</span>

        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get neighbors for each atom in the unit cell, out to a distance r</span>
<span class="sd">        Returns a list of list of neighbors for each site in structure.</span>
<span class="sd">        Use this method if you are planning on looping over all sites in the</span>
<span class="sd">        crystal. If you only want neighbors for a particular site, use the</span>
<span class="sd">        method get_neighbors as it may not have to build such a large supercell</span>
<span class="sd">        However if you are looping over all sites in the crystal, this method</span>
<span class="sd">        is more efficient since it only performs one pass over a large enough</span>
<span class="sd">        supercell to contain all possible atoms out to a distance r.</span>
<span class="sd">        The return type is a [(site, dist) ...] since most of the time,</span>
<span class="sd">        subsequent processing requires the distance.</span>

<span class="sd">        A note about periodic images: Before computing the neighbors, this</span>
<span class="sd">        operation translates all atoms to within the unit cell (having</span>
<span class="sd">        fractional coordinates within [0,1)). This means that the &quot;image&quot; of a</span>
<span class="sd">        site does not correspond to how much it has been translates from its</span>
<span class="sd">        current position, but which image of the unit cell it resides.</span>

<span class="sd">        Args:</span>
<span class="sd">            r (float): Radius of sphere.</span>
<span class="sd">            include_index (bool): Deprecated. Now, the non-supercell site index</span>
<span class="sd">                is always included in the returned data.</span>
<span class="sd">            include_image (bool): Deprecated. Now the supercell image</span>
<span class="sd">                is always included in the returned data.</span>
<span class="sd">            sites (list of Sites or None): sites for getting all neighbors,</span>
<span class="sd">                default is None, which means neighbors will be obtained for all</span>
<span class="sd">                sites. This is useful in the situation where you are interested</span>
<span class="sd">                only in one subspecies type, and makes it a lot faster.</span>
<span class="sd">            numerical_tol (float): This is a numerical tolerance for distances.</span>
<span class="sd">                Sites which are &lt; numerical_tol are determined to be conincident</span>
<span class="sd">                with the site. Sites which are r + numerical_tol away is deemed</span>
<span class="sd">                to be within r from the site. The default of 1e-8 should be</span>
<span class="sd">                ok in most instances.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [PeriodicNeighbor] where PeriodicNeighbor is a namedtuple containing</span>
<span class="sd">            (site, distance, index, image).</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">if</span> <span class="n">sites</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">sites</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">sites</span>
        <span class="n">site_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">])</span>
        <span class="n">point_neighbors</span> <span class="o">=</span> <span class="n">get_points_in_spheres</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">,</span> <span class="n">site_coords</span><span class="p">,</span> <span class="n">r</span><span class="o">=</span><span class="n">r</span><span class="p">,</span> <span class="n">pbc</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                                                <span class="n">numerical_tol</span><span class="o">=</span><span class="n">numerical_tol</span><span class="p">,</span> <span class="n">lattice</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="p">)</span>
        <span class="n">neighbors</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">List</span><span class="p">[</span><span class="n">PeriodicNeighbor</span><span class="p">]]</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">point_neighbor</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">point_neighbors</span><span class="p">,</span> <span class="n">sites</span><span class="p">):</span>
            <span class="n">nns</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">PeriodicNeighbor</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">point_neighbor</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>
                <span class="n">neighbors</span><span class="o">.</span><span class="n">append</span><span class="p">([])</span>
                <span class="k">continue</span>
            <span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="n">point_neighbor</span><span class="p">:</span>
                <span class="n">coord</span><span class="p">,</span> <span class="n">d</span><span class="p">,</span> <span class="n">index</span><span class="p">,</span> <span class="n">image</span> <span class="o">=</span> <span class="n">n</span>
                <span class="k">if</span> <span class="p">(</span><span class="n">d</span> <span class="o">&gt;</span> <span class="n">numerical_tol</span><span class="p">)</span> <span class="ow">or</span> <span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span> <span class="o">!=</span> <span class="n">site</span><span class="p">):</span>
                    <span class="n">neighbor</span> <span class="o">=</span> <span class="n">PeriodicNeighbor</span><span class="p">(</span>
                        <span class="n">species</span><span class="o">=</span><span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span><span class="o">.</span><span class="n">species</span><span class="p">,</span>
                        <span class="n">coords</span><span class="o">=</span><span class="n">coord</span><span class="p">,</span>
                        <span class="n">lattice</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="p">,</span>
                        <span class="n">properties</span><span class="o">=</span><span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                        <span class="n">nn_distance</span><span class="o">=</span><span class="n">d</span><span class="p">,</span>
                        <span class="n">index</span><span class="o">=</span><span class="n">index</span><span class="p">,</span>
                        <span class="n">image</span><span class="o">=</span><span class="nb">tuple</span><span class="p">(</span><span class="n">image</span><span class="p">)</span>
                    <span class="p">)</span>
                    <span class="n">nns</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">neighbor</span><span class="p">)</span>
            <span class="n">neighbors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">nns</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">neighbors</span></div>

    <span class="nd">@deprecated</span><span class="p">(</span><span class="n">get_all_neighbors</span><span class="p">,</span> <span class="s2">&quot;This is retained purely for checking purposes.&quot;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">get_all_neighbors_old</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">r</span><span class="p">,</span> <span class="n">include_index</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">include_image</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
                              <span class="n">include_site</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get neighbors for each atom in the unit cell, out to a distance r</span>
<span class="sd">        Returns a list of list of neighbors for each site in structure.</span>
<span class="sd">        Use this method if you are planning on looping over all sites in the</span>
<span class="sd">        crystal. If you only want neighbors for a particular site, use the</span>
<span class="sd">        method get_neighbors as it may not have to build such a large supercell</span>
<span class="sd">        However if you are looping over all sites in the crystal, this method</span>
<span class="sd">        is more efficient since it only performs one pass over a large enough</span>
<span class="sd">        supercell to contain all possible atoms out to a distance r.</span>
<span class="sd">        The return type is a [(site, dist) ...] since most of the time,</span>
<span class="sd">        subsequent processing requires the distance.</span>

<span class="sd">        A note about periodic images: Before computing the neighbors, this</span>
<span class="sd">        operation translates all atoms to within the unit cell (having</span>
<span class="sd">        fractional coordinates within [0,1)). This means that the &quot;image&quot; of a</span>
<span class="sd">        site does not correspond to how much it has been translates from its</span>
<span class="sd">        current position, but which image of the unit cell it resides.</span>

<span class="sd">        Args:</span>
<span class="sd">            r (float): Radius of sphere.</span>
<span class="sd">            include_index (bool): Whether to include the non-supercell site</span>
<span class="sd">                in the returned data</span>
<span class="sd">            include_image (bool): Whether to include the supercell image</span>
<span class="sd">                in the returned data</span>
<span class="sd">            include_site (bool): Whether to include the site in the returned</span>
<span class="sd">                data. Defaults to True.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [Neighbor] where Neighbor is a namedtuple containing</span>
<span class="sd">            (site, distance, index, image).</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="c1"># Use same algorithm as get_sites_in_sphere to determine supercell but</span>
        <span class="c1"># loop over all atoms in crystal</span>
        <span class="n">recp_len</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">reciprocal_lattice</span><span class="o">.</span><span class="n">abc</span><span class="p">)</span>
        <span class="n">maxr</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">ceil</span><span class="p">((</span><span class="n">r</span> <span class="o">+</span> <span class="mf">0.15</span><span class="p">)</span> <span class="o">*</span> <span class="n">recp_len</span> <span class="o">/</span> <span class="p">(</span><span class="mi">2</span> <span class="o">*</span> <span class="n">math</span><span class="o">.</span><span class="n">pi</span><span class="p">))</span>
        <span class="n">nmin</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">floor</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">min</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">))</span> <span class="o">-</span> <span class="n">maxr</span>
        <span class="n">nmax</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">ceil</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">max</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">))</span> <span class="o">+</span> <span class="n">maxr</span>

        <span class="n">all_ranges</span> <span class="o">=</span> <span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">nmin</span><span class="p">,</span> <span class="n">nmax</span><span class="p">)]</span>
        <span class="n">latt</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span>
        <span class="n">matrix</span> <span class="o">=</span> <span class="n">latt</span><span class="o">.</span><span class="n">matrix</span>
        <span class="n">neighbors</span> <span class="o">=</span> <span class="p">[</span><span class="nb">list</span><span class="p">()</span> <span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">))]</span>
        <span class="n">all_fcoords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">mod</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
        <span class="n">coords_in_cell</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">all_fcoords</span><span class="p">,</span> <span class="n">matrix</span><span class="p">)</span>
        <span class="n">site_coords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span>

        <span class="n">indices</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>

        <span class="k">for</span> <span class="n">image</span> <span class="ow">in</span> <span class="n">itertools</span><span class="o">.</span><span class="n">product</span><span class="p">(</span><span class="o">*</span><span class="n">all_ranges</span><span class="p">):</span>
            <span class="n">coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">image</span><span class="p">,</span> <span class="n">matrix</span><span class="p">)</span> <span class="o">+</span> <span class="n">coords_in_cell</span>
            <span class="n">all_dists</span> <span class="o">=</span> <span class="n">all_distances</span><span class="p">(</span><span class="n">coords</span><span class="p">,</span> <span class="n">site_coords</span><span class="p">)</span>
            <span class="n">all_within_r</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">bitwise_and</span><span class="p">(</span><span class="n">all_dists</span> <span class="o">&lt;=</span> <span class="n">r</span><span class="p">,</span> <span class="n">all_dists</span> <span class="o">&gt;</span> <span class="mf">1e-8</span><span class="p">)</span>

            <span class="k">for</span> <span class="p">(</span><span class="n">j</span><span class="p">,</span> <span class="n">d</span><span class="p">,</span> <span class="n">within_r</span><span class="p">)</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">indices</span><span class="p">,</span> <span class="n">all_dists</span><span class="p">,</span> <span class="n">all_within_r</span><span class="p">):</span>
                <span class="k">if</span> <span class="n">include_site</span><span class="p">:</span>
                    <span class="n">nnsite</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">]</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">[</span><span class="n">j</span><span class="p">],</span>
                                          <span class="n">latt</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                                          <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                                          <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

                <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">[</span><span class="n">within_r</span><span class="p">]:</span>
                    <span class="n">item</span> <span class="o">=</span> <span class="p">[]</span>
                    <span class="k">if</span> <span class="n">include_site</span><span class="p">:</span>
                        <span class="n">item</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">nnsite</span><span class="p">)</span>
                    <span class="n">item</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">d</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
                    <span class="k">if</span> <span class="n">include_index</span><span class="p">:</span>
                        <span class="n">item</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">j</span><span class="p">)</span>
                    <span class="c1"># Add the image, if requested</span>
                    <span class="k">if</span> <span class="n">include_image</span><span class="p">:</span>
                        <span class="n">item</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">image</span><span class="p">)</span>
                    <span class="n">neighbors</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">item</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">neighbors</span>

<div class="viewcode-block" id="IStructure.get_neighbors_in_shell"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_neighbors_in_shell">[docs]</a>    <span class="k">def</span> <span class="nf">get_neighbors_in_shell</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">origin</span><span class="p">,</span> <span class="n">r</span><span class="p">,</span> <span class="n">dr</span><span class="p">,</span> <span class="n">include_index</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">include_image</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns all sites in a shell centered on origin (coords) between radii</span>
<span class="sd">        r-dr and r+dr.</span>

<span class="sd">        Args:</span>
<span class="sd">            origin (3x1 array): Cartesian coordinates of center of sphere.</span>
<span class="sd">            r (float): Inner radius of shell.</span>
<span class="sd">            dr (float): Width of shell.</span>
<span class="sd">            include_index (bool): Deprecated. Now, the non-supercell site index</span>
<span class="sd">                is always included in the returned data.</span>
<span class="sd">            include_image (bool): Deprecated. Now the supercell image</span>
<span class="sd">                is always included in the returned data.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [NearestNeighbor] where Nearest Neighbor is a named tuple containing</span>
<span class="sd">            (site, distance, index, image).</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">outer</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_sites_in_sphere</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">r</span> <span class="o">+</span> <span class="n">dr</span><span class="p">,</span>
                                         <span class="n">include_index</span><span class="o">=</span><span class="n">include_index</span><span class="p">,</span>
                                         <span class="n">include_image</span><span class="o">=</span><span class="n">include_image</span><span class="p">)</span>
        <span class="n">inner</span> <span class="o">=</span> <span class="n">r</span> <span class="o">-</span> <span class="n">dr</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">t</span> <span class="k">for</span> <span class="n">t</span> <span class="ow">in</span> <span class="n">outer</span> <span class="k">if</span> <span class="n">t</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">&gt;</span> <span class="n">inner</span><span class="p">]</span></div>

<div class="viewcode-block" id="IStructure.get_sorted_structure"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_sorted_structure">[docs]</a>    <span class="k">def</span> <span class="nf">get_sorted_structure</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get a sorted copy of the structure. The parameters have the same</span>
<span class="sd">        meaning as in list.sort. By default, sites are sorted by the</span>
<span class="sd">        electronegativity of the species.</span>

<span class="sd">        Args:</span>
<span class="sd">            key: Specifies a function of one argument that is used to extract</span>
<span class="sd">                a comparison key from each list element: key=str.lower. The</span>
<span class="sd">                default value is None (compare the elements directly).</span>
<span class="sd">            reverse (bool): If set to True, then the list elements are sorted</span>
<span class="sd">                as if each comparison were reversed.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">sites</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">key</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="n">reverse</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">sites</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.get_reduced_structure"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_reduced_structure">[docs]</a>    <span class="k">def</span> <span class="nf">get_reduced_structure</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">reduction_algo</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;niggli&quot;</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get a reduced structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            reduction_algo (str): The lattice reduction algorithm to use.</span>
<span class="sd">                Currently supported options are &quot;niggli&quot; or &quot;LLL&quot;.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">reduction_algo</span> <span class="o">==</span> <span class="s2">&quot;niggli&quot;</span><span class="p">:</span>
            <span class="n">reduced_latt</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_niggli_reduced_lattice</span><span class="p">()</span>
        <span class="k">elif</span> <span class="n">reduction_algo</span> <span class="o">==</span> <span class="s2">&quot;LLL&quot;</span><span class="p">:</span>
            <span class="n">reduced_latt</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_lll_reduced_lattice</span><span class="p">()</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Invalid reduction algo : </span><span class="si">{}</span><span class="s2">&quot;</span>
                             <span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">reduction_algo</span><span class="p">))</span>

        <span class="k">if</span> <span class="n">reduced_latt</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="p">(</span>  <span class="c1"># type: ignore</span>
                <span class="n">reduced_latt</span><span class="p">,</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">species_and_occu</span><span class="p">,</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">,</span>
                <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                <span class="n">to_unit_cell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                <span class="n">site_properties</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span><span class="p">,</span>
                <span class="n">charge</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span></div>

<div class="viewcode-block" id="IStructure.copy"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.copy">[docs]</a>    <span class="k">def</span> <span class="nf">copy</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">site_properties</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">sanitize</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Convenience method to get a copy of the structure, with options to add</span>
<span class="sd">        site properties.</span>

<span class="sd">        Args:</span>
<span class="sd">            site_properties (dict): Properties to add or override. The</span>
<span class="sd">                properties are specified in the same way as the constructor,</span>
<span class="sd">                i.e., as a dict of the form {property: [values]}. The</span>
<span class="sd">                properties should be in the order of the *original* structure</span>
<span class="sd">                if you are performing sanitization.</span>
<span class="sd">            sanitize (bool): If True, this method will return a sanitized</span>
<span class="sd">                structure. Sanitization performs a few things: (i) The sites are</span>
<span class="sd">                sorted by electronegativity, (ii) a LLL lattice reduction is</span>
<span class="sd">                carried out to obtain a relatively orthogonalized cell,</span>
<span class="sd">                (iii) all fractional coords for sites are mapped into the</span>
<span class="sd">                unit cell.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A copy of the Structure, with optionally new site_properties and</span>
<span class="sd">            optionally sanitized.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">props</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span>
        <span class="k">if</span> <span class="n">site_properties</span><span class="p">:</span>
            <span class="n">props</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">site_properties</span><span class="p">)</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">sanitize</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                  <span class="bp">self</span><span class="o">.</span><span class="n">species_and_occu</span><span class="p">,</span>
                                  <span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span>
                                  <span class="n">charge</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span>
                                  <span class="n">site_properties</span><span class="o">=</span><span class="n">props</span><span class="p">)</span>
        <span class="n">reduced_latt</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_lll_reduced_lattice</span><span class="p">()</span>
        <span class="n">new_sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
            <span class="n">frac_coords</span> <span class="o">=</span> <span class="n">reduced_latt</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">)</span>
            <span class="n">site_props</span> <span class="o">=</span> <span class="p">{}</span>
            <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">props</span><span class="p">:</span>
                <span class="n">site_props</span><span class="p">[</span><span class="n">p</span><span class="p">]</span> <span class="o">=</span> <span class="n">props</span><span class="p">[</span><span class="n">p</span><span class="p">][</span><span class="n">i</span><span class="p">]</span>
            <span class="n">new_sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">PeriodicSite</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span>
                                          <span class="n">frac_coords</span><span class="p">,</span> <span class="n">reduced_latt</span><span class="p">,</span>
                                          <span class="n">to_unit_cell</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                                          <span class="n">properties</span><span class="o">=</span><span class="n">site_props</span><span class="p">,</span>
                                          <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">))</span>
        <span class="n">new_sites</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">new_sites</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">new_sites</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.interpolate"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.interpolate">[docs]</a>    <span class="k">def</span> <span class="nf">interpolate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">end_structure</span><span class="p">,</span>
                    <span class="n">nimages</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="n">Iterable</span><span class="p">]</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
                    <span class="n">interpolate_lattices</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                    <span class="n">pbc</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>
                    <span class="n">autosort_tol</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mi">0</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Interpolate between this structure and end_structure. Useful for</span>
<span class="sd">        construction of NEB inputs.</span>

<span class="sd">        Args:</span>
<span class="sd">            end_structure (Structure): structure to interpolate between this</span>
<span class="sd">                structure and end.</span>
<span class="sd">            nimages (int,list): No. of interpolation images or a list of</span>
<span class="sd">                interpolation images. Defaults to 10 images.</span>
<span class="sd">            interpolate_lattices (bool): Whether to interpolate the lattices.</span>
<span class="sd">                Interpolates the lengths and angles (rather than the matrix)</span>
<span class="sd">                so orientation may be affected.</span>
<span class="sd">            pbc (bool): Whether to use periodic boundary conditions to find</span>
<span class="sd">                the shortest path between endpoints.</span>
<span class="sd">            autosort_tol (float): A distance tolerance in angstrom in</span>
<span class="sd">                which to automatically sort end_structure to match to the</span>
<span class="sd">                closest points in this particular structure. This is usually</span>
<span class="sd">                what you want in a NEB calculation. 0 implies no sorting.</span>
<span class="sd">                Otherwise, a 0.5 value usually works pretty well.</span>

<span class="sd">        Returns:</span>
<span class="sd">            List of interpolated structures. The starting and ending</span>
<span class="sd">            structures included as the first and last structures respectively.</span>
<span class="sd">            A total of (nimages + 1) structures are returned.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="c1"># Check length of structures</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">end_structure</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Structures have different lengths!&quot;</span><span class="p">)</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">interpolate_lattices</span> <span class="ow">or</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span> <span class="o">==</span> <span class="n">end_structure</span><span class="o">.</span><span class="n">lattice</span><span class="p">):</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Structures with different lattices!&quot;</span><span class="p">)</span>

        <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">nimages</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Iterable</span><span class="p">):</span>
            <span class="n">images</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">nimages</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="n">nimages</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">images</span> <span class="o">=</span> <span class="n">nimages</span>

        <span class="c1"># Check that both structures have the same species</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
            <span class="k">if</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="o">!=</span> <span class="n">end_structure</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">species</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Different species!</span><span class="se">\n</span><span class="s2">Structure 1:</span><span class="se">\n</span><span class="s2">&quot;</span> <span class="o">+</span>
                                 <span class="nb">str</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">Structure 2</span><span class="se">\n</span><span class="s2">&quot;</span> <span class="o">+</span>
                                 <span class="nb">str</span><span class="p">(</span><span class="n">end_structure</span><span class="p">))</span>

        <span class="n">start_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">)</span>
        <span class="n">end_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">end_structure</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">)</span>

        <span class="k">if</span> <span class="n">autosort_tol</span><span class="p">:</span>
            <span class="n">dist_matrix</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">get_all_distances</span><span class="p">(</span><span class="n">start_coords</span><span class="p">,</span>
                                                         <span class="n">end_coords</span><span class="p">)</span>
            <span class="n">site_mappings</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>  <span class="c1"># type: Dict[int, List[int]]</span>
            <span class="n">unmapped_start_ind</span> <span class="o">=</span> <span class="p">[]</span>
            <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">row</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">dist_matrix</span><span class="p">):</span>
                <span class="n">ind</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">row</span> <span class="o">&lt;</span> <span class="n">autosort_tol</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
                <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">ind</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
                    <span class="n">site_mappings</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">ind</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="n">unmapped_start_ind</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>

            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">unmapped_start_ind</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Unable to reliably match structures &quot;</span>
                                 <span class="s2">&quot;with auto_sort_tol = </span><span class="si">%f</span><span class="s2">. unmapped indices &quot;</span>
                                 <span class="s2">&quot;= </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">autosort_tol</span><span class="p">,</span> <span class="n">unmapped_start_ind</span><span class="p">))</span>

            <span class="n">sorted_end_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros_like</span><span class="p">(</span><span class="n">end_coords</span><span class="p">)</span>
            <span class="n">matched</span> <span class="o">=</span> <span class="p">[]</span>
            <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">site_mappings</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">j</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
                    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Unable to reliably match structures &quot;</span>
                                     <span class="s2">&quot;with auto_sort_tol = </span><span class="si">%f</span><span class="s2">. More than one &quot;</span>
                                     <span class="s2">&quot;site match!&quot;</span> <span class="o">%</span> <span class="n">autosort_tol</span><span class="p">)</span>
                <span class="n">sorted_end_coords</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">end_coords</span><span class="p">[</span><span class="n">j</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span>
                <span class="n">matched</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">j</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>

            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">unmapped_start_ind</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
                <span class="n">i</span> <span class="o">=</span> <span class="n">unmapped_start_ind</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
                <span class="n">j</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="nb">set</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">start_coords</span><span class="p">)))</span><span class="o">.</span><span class="n">difference</span><span class="p">(</span><span class="n">matched</span><span class="p">))[</span><span class="mi">0</span><span class="p">]</span>  <span class="c1"># type: ignore</span>
                <span class="n">sorted_end_coords</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">end_coords</span><span class="p">[</span><span class="n">j</span><span class="p">]</span>

            <span class="n">end_coords</span> <span class="o">=</span> <span class="n">sorted_end_coords</span>

        <span class="n">vec</span> <span class="o">=</span> <span class="n">end_coords</span> <span class="o">-</span> <span class="n">start_coords</span>
        <span class="k">if</span> <span class="n">pbc</span><span class="p">:</span>
            <span class="n">vec</span> <span class="o">-=</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">vec</span><span class="p">)</span>
        <span class="n">sp</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">species_and_occu</span>
        <span class="n">structs</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="k">if</span> <span class="n">interpolate_lattices</span><span class="p">:</span>
            <span class="c1"># interpolate lattice matrices using polar decomposition</span>
            <span class="kn">from</span> <span class="nn">scipy.linalg</span> <span class="kn">import</span> <span class="n">polar</span>
            <span class="c1"># u is unitary (rotation), p is stretch</span>
            <span class="n">u</span><span class="p">,</span> <span class="n">p</span> <span class="o">=</span> <span class="n">polar</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">end_structure</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">matrix</span><span class="o">.</span><span class="n">T</span><span class="p">,</span>
                                <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">inv</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">matrix</span><span class="o">.</span><span class="n">T</span><span class="p">)))</span>
            <span class="n">lvec</span> <span class="o">=</span> <span class="n">p</span> <span class="o">-</span> <span class="n">np</span><span class="o">.</span><span class="n">identity</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
            <span class="n">lstart</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">matrix</span><span class="o">.</span><span class="n">T</span>

        <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">images</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">interpolate_lattices</span><span class="p">:</span>
                <span class="n">l_a</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">identity</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="o">+</span> <span class="n">x</span> <span class="o">*</span> <span class="n">lvec</span><span class="p">,</span> <span class="n">lstart</span><span class="p">)</span><span class="o">.</span><span class="n">T</span>
                <span class="n">lat</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">l_a</span><span class="p">)</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="n">lat</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span>
            <span class="n">fcoords</span> <span class="o">=</span> <span class="n">start_coords</span> <span class="o">+</span> <span class="n">x</span> <span class="o">*</span> <span class="n">vec</span>
            <span class="n">structs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="p">(</span><span class="n">lat</span><span class="p">,</span> <span class="n">sp</span><span class="p">,</span> <span class="n">fcoords</span><span class="p">,</span> <span class="n">site_properties</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span><span class="p">))</span>  <span class="c1"># type: ignore</span>
        <span class="k">return</span> <span class="n">structs</span></div>

<div class="viewcode-block" id="IStructure.get_miller_index_from_site_indexes"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_miller_index_from_site_indexes">[docs]</a>    <span class="k">def</span> <span class="nf">get_miller_index_from_site_indexes</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">site_ids</span><span class="p">,</span> <span class="n">round_dp</span><span class="o">=</span><span class="mi">4</span><span class="p">,</span>
                                           <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get the Miller index of a plane from a set of sites indexes.</span>

<span class="sd">        A minimum of 3 sites are required. If more than 3 sites are given</span>
<span class="sd">        the best plane that minimises the distance to all points will be</span>
<span class="sd">        calculated.</span>

<span class="sd">        Args:</span>
<span class="sd">            site_ids (list of int): A list of site indexes to consider. A</span>
<span class="sd">                minimum of three site indexes are required. If more than three</span>
<span class="sd">                sites are provided, the best plane that minimises the distance</span>
<span class="sd">                to all sites will be calculated.</span>
<span class="sd">            round_dp (int, optional): The number of decimal places to round the</span>
<span class="sd">                miller index to.</span>
<span class="sd">            verbose (bool, optional): Whether to print warnings.</span>

<span class="sd">        Returns:</span>
<span class="sd">            (tuple): The Miller index.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">get_miller_index_from_coords</span><span class="p">(</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">[</span><span class="n">site_ids</span><span class="p">],</span> <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
            <span class="n">round_dp</span><span class="o">=</span><span class="n">round_dp</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="n">verbose</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.get_primitive_structure"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.get_primitive_structure">[docs]</a>    <span class="k">def</span> <span class="nf">get_primitive_structure</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tolerance</span><span class="o">=</span><span class="mf">0.25</span><span class="p">,</span> <span class="n">use_site_props</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
                                <span class="n">constrain_latt</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        This finds a smaller unit cell than the input. Sometimes it doesn&quot;t</span>
<span class="sd">        find the smallest possible one, so this method is recursively called</span>
<span class="sd">        until it is unable to find a smaller cell.</span>

<span class="sd">        NOTE: if the tolerance is greater than 1/2 the minimum inter-site</span>
<span class="sd">        distance in the primitive cell, the algorithm will reject this lattice.</span>

<span class="sd">        Args:</span>
<span class="sd">            tolerance (float), Angstroms: Tolerance for each coordinate of a</span>
<span class="sd">                particular site. For example, [0.1, 0, 0.1] in cartesian</span>
<span class="sd">                coordinates will be considered to be on the same coordinates</span>
<span class="sd">                as [0, 0, 0] for a tolerance of 0.25. Defaults to 0.25.</span>
<span class="sd">            use_site_props (bool): Whether to account for site properties in</span>
<span class="sd">                differntiating sites.</span>
<span class="sd">            constrain_latt (list/dict): List of lattice parameters we want to</span>
<span class="sd">                preserve, e.g. [&quot;alpha&quot;, &quot;c&quot;] or dict with the lattice</span>
<span class="sd">                parameter names as keys and values we want the parameters to</span>
<span class="sd">                be e.g. {&quot;alpha&quot;: 90, &quot;c&quot;: 2.5}.</span>

<span class="sd">        Returns:</span>
<span class="sd">            The most primitive structure found.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">constrain_latt</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">constrain_latt</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="k">def</span> <span class="nf">site_label</span><span class="p">(</span><span class="n">site</span><span class="p">):</span>
            <span class="k">if</span> <span class="ow">not</span> <span class="n">use_site_props</span><span class="p">:</span>
                <span class="k">return</span> <span class="n">site</span><span class="o">.</span><span class="n">species_string</span>
            <span class="n">d</span> <span class="o">=</span> <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">species_string</span><span class="p">]</span>
            <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="o">.</span><span class="n">keys</span><span class="p">()):</span>
                <span class="n">d</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">k</span> <span class="o">+</span> <span class="s2">&quot;=&quot;</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="n">k</span><span class="p">]))</span>
            <span class="k">return</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>

        <span class="c1"># group sites by species string</span>
        <span class="n">sites</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">site_label</span><span class="p">)</span>

        <span class="n">grouped_sites</span> <span class="o">=</span> <span class="p">[</span>
            <span class="nb">list</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
            <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">itertools</span><span class="o">.</span><span class="n">groupby</span><span class="p">(</span><span class="n">sites</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="n">site_label</span><span class="p">)]</span>
        <span class="n">grouped_fcoords</span> <span class="o">=</span> <span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="n">s</span><span class="o">.</span><span class="n">frac_coords</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">g</span><span class="p">])</span>
                           <span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">grouped_sites</span><span class="p">]</span>

        <span class="c1"># min_vecs are approximate periodicities of the cell. The exact</span>
        <span class="c1"># periodicities from the supercell matrices are checked against these</span>
        <span class="c1"># first</span>
        <span class="n">min_fcoords</span> <span class="o">=</span> <span class="nb">min</span><span class="p">(</span><span class="n">grouped_fcoords</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">))</span>
        <span class="n">min_vecs</span> <span class="o">=</span> <span class="n">min_fcoords</span> <span class="o">-</span> <span class="n">min_fcoords</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>

        <span class="c1"># fractional tolerance in the supercell</span>
        <span class="n">super_ftol</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">divide</span><span class="p">(</span><span class="n">tolerance</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">abc</span><span class="p">)</span>
        <span class="n">super_ftol_2</span> <span class="o">=</span> <span class="n">super_ftol</span> <span class="o">*</span> <span class="mi">2</span>

        <span class="k">def</span> <span class="nf">pbc_coord_intersection</span><span class="p">(</span><span class="n">fc1</span><span class="p">,</span> <span class="n">fc2</span><span class="p">,</span> <span class="n">tol</span><span class="p">):</span>
            <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">            Returns the fractional coords in fc1 that have coordinates</span>
<span class="sd">            within tolerance to some coordinate in fc2</span>
<span class="sd">            &quot;&quot;&quot;</span>
            <span class="n">d</span> <span class="o">=</span> <span class="n">fc1</span><span class="p">[:,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:]</span> <span class="o">-</span> <span class="n">fc2</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="p">:,</span> <span class="p">:]</span>
            <span class="n">d</span> <span class="o">-=</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
            <span class="n">np</span><span class="o">.</span><span class="n">abs</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">d</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">fc1</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">any</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">d</span> <span class="o">&lt;</span> <span class="n">tol</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">),</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)]</span>

        <span class="c1"># here we reduce the number of min_vecs by enforcing that every</span>
        <span class="c1"># vector in min_vecs approximately maps each site onto a similar site.</span>
        <span class="c1"># The subsequent processing is O(fu^3 * min_vecs) = O(n^4) if we do no</span>
        <span class="c1"># reduction.</span>
        <span class="c1"># This reduction is O(n^3) so usually is an improvement. Using double</span>
        <span class="c1"># the tolerance because both vectors are approximate</span>
        <span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">grouped_fcoords</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="nb">len</span><span class="p">(</span><span class="n">x</span><span class="p">)):</span>
            <span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">g</span><span class="p">:</span>
                <span class="n">min_vecs</span> <span class="o">=</span> <span class="n">pbc_coord_intersection</span><span class="p">(</span><span class="n">min_vecs</span><span class="p">,</span> <span class="n">g</span> <span class="o">-</span> <span class="n">f</span><span class="p">,</span> <span class="n">super_ftol_2</span><span class="p">)</span>

        <span class="k">def</span> <span class="nf">get_hnf</span><span class="p">(</span><span class="n">fu</span><span class="p">):</span>
            <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">            Returns all possible distinct supercell matrices given a</span>
<span class="sd">            number of formula units in the supercell. Batches the matrices</span>
<span class="sd">            by the values in the diagonal (for less numpy overhead).</span>
<span class="sd">            Computational complexity is O(n^3), and difficult to improve.</span>
<span class="sd">            Might be able to do something smart with checking combinations of a</span>
<span class="sd">            and b first, though unlikely to reduce to O(n^2).</span>
<span class="sd">            &quot;&quot;&quot;</span>

            <span class="k">def</span> <span class="nf">factors</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
                <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="n">n</span> <span class="o">+</span> <span class="mi">1</span><span class="p">):</span>
                    <span class="k">if</span> <span class="n">n</span> <span class="o">%</span> <span class="n">i</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
                        <span class="k">yield</span> <span class="n">i</span>

            <span class="k">for</span> <span class="n">det</span> <span class="ow">in</span> <span class="n">factors</span><span class="p">(</span><span class="n">fu</span><span class="p">):</span>
                <span class="k">if</span> <span class="n">det</span> <span class="o">==</span> <span class="mi">1</span><span class="p">:</span>
                    <span class="k">continue</span>
                <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">factors</span><span class="p">(</span><span class="n">det</span><span class="p">):</span>
                    <span class="k">for</span> <span class="n">e</span> <span class="ow">in</span> <span class="n">factors</span><span class="p">(</span><span class="n">det</span> <span class="o">//</span> <span class="n">a</span><span class="p">):</span>
                        <span class="n">g</span> <span class="o">=</span> <span class="n">det</span> <span class="o">//</span> <span class="n">a</span> <span class="o">//</span> <span class="n">e</span>
                        <span class="k">yield</span> <span class="n">det</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span>
                            <span class="p">[[[</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">f</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">g</span><span class="p">]]</span>
                             <span class="k">for</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">f</span> <span class="ow">in</span>
                             <span class="n">itertools</span><span class="o">.</span><span class="n">product</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="nb">range</span><span class="p">(</span><span class="n">a</span><span class="p">),</span>
                                               <span class="nb">range</span><span class="p">(</span><span class="n">e</span><span class="p">))])</span>

        <span class="c1"># we cant let sites match to their neighbors in the supercell</span>
        <span class="n">grouped_non_nbrs</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">gfcoords</span> <span class="ow">in</span> <span class="n">grouped_fcoords</span><span class="p">:</span>
            <span class="n">fdist</span> <span class="o">=</span> <span class="n">gfcoords</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="p">:,</span> <span class="p">:]</span> <span class="o">-</span> <span class="n">gfcoords</span><span class="p">[:,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:]</span>
            <span class="n">fdist</span> <span class="o">-=</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">fdist</span><span class="p">)</span>
            <span class="n">np</span><span class="o">.</span><span class="n">abs</span><span class="p">(</span><span class="n">fdist</span><span class="p">,</span> <span class="n">fdist</span><span class="p">)</span>
            <span class="n">non_nbrs</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">any</span><span class="p">(</span><span class="n">fdist</span> <span class="o">&gt;</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">super_ftol</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:],</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
            <span class="c1"># since we want sites to match to themselves</span>
            <span class="n">np</span><span class="o">.</span><span class="n">fill_diagonal</span><span class="p">(</span><span class="n">non_nbrs</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span>
            <span class="n">grouped_non_nbrs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">non_nbrs</span><span class="p">)</span>

        <span class="n">num_fu</span> <span class="o">=</span> <span class="n">functools</span><span class="o">.</span><span class="n">reduce</span><span class="p">(</span><span class="n">math</span><span class="o">.</span><span class="n">gcd</span><span class="p">,</span> <span class="nb">map</span><span class="p">(</span><span class="nb">len</span><span class="p">,</span> <span class="n">grouped_sites</span><span class="p">))</span>
        <span class="k">for</span> <span class="n">size</span><span class="p">,</span> <span class="n">ms</span> <span class="ow">in</span> <span class="n">get_hnf</span><span class="p">(</span><span class="n">num_fu</span><span class="p">):</span>
            <span class="n">inv_ms</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">inv</span><span class="p">(</span><span class="n">ms</span><span class="p">)</span>

            <span class="c1"># find sets of lattice vectors that are are present in min_vecs</span>
            <span class="n">dist</span> <span class="o">=</span> <span class="n">inv_ms</span><span class="p">[:,</span> <span class="p">:,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:]</span> <span class="o">-</span> <span class="n">min_vecs</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:,</span> <span class="p">:]</span>
            <span class="n">dist</span> <span class="o">-=</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">dist</span><span class="p">)</span>
            <span class="n">np</span><span class="o">.</span><span class="n">abs</span><span class="p">(</span><span class="n">dist</span><span class="p">,</span> <span class="n">dist</span><span class="p">)</span>
            <span class="n">is_close</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">dist</span> <span class="o">&lt;</span> <span class="n">super_ftol</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
            <span class="n">any_close</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">any</span><span class="p">(</span><span class="n">is_close</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
            <span class="n">inds</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">any_close</span><span class="p">,</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>

            <span class="k">for</span> <span class="n">inv_m</span><span class="p">,</span> <span class="n">m</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">inv_ms</span><span class="p">[</span><span class="n">inds</span><span class="p">],</span> <span class="n">ms</span><span class="p">[</span><span class="n">inds</span><span class="p">]):</span>
                <span class="n">new_m</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">inv_m</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">matrix</span><span class="p">)</span>
                <span class="n">ftol</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">divide</span><span class="p">(</span><span class="n">tolerance</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">new_m</span> <span class="o">**</span> <span class="mi">2</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">1</span><span class="p">)))</span>

                <span class="n">valid</span> <span class="o">=</span> <span class="kc">True</span>
                <span class="n">new_coords</span> <span class="o">=</span> <span class="p">[]</span>
                <span class="n">new_sp</span> <span class="o">=</span> <span class="p">[]</span>
                <span class="n">new_props</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
                <span class="k">for</span> <span class="n">gsites</span><span class="p">,</span> <span class="n">gfcoords</span><span class="p">,</span> <span class="n">non_nbrs</span> <span class="ow">in</span> <span class="nb">zip</span><span class="p">(</span><span class="n">grouped_sites</span><span class="p">,</span>
                                                      <span class="n">grouped_fcoords</span><span class="p">,</span>
                                                      <span class="n">grouped_non_nbrs</span><span class="p">):</span>
                    <span class="n">all_frac</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">gfcoords</span><span class="p">,</span> <span class="n">m</span><span class="p">)</span>

                    <span class="c1"># calculate grouping of equivalent sites, represented by</span>
                    <span class="c1"># adjacency matrix</span>
                    <span class="n">fdist</span> <span class="o">=</span> <span class="n">all_frac</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="p">:,</span> <span class="p">:]</span> <span class="o">-</span> <span class="n">all_frac</span><span class="p">[:,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:]</span>
                    <span class="n">fdist</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">abs</span><span class="p">(</span><span class="n">fdist</span> <span class="o">-</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">fdist</span><span class="p">))</span>
                    <span class="n">close_in_prim</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">fdist</span> <span class="o">&lt;</span> <span class="n">ftol</span><span class="p">[</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="p">:],</span> <span class="n">axis</span><span class="o">=-</span><span class="mi">1</span><span class="p">)</span>
                    <span class="n">groups</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">logical_and</span><span class="p">(</span><span class="n">close_in_prim</span><span class="p">,</span> <span class="n">non_nbrs</span><span class="p">)</span>

                    <span class="c1"># check that groups are correct</span>
                    <span class="k">if</span> <span class="ow">not</span> <span class="n">np</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">groups</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">size</span><span class="p">):</span>
                        <span class="n">valid</span> <span class="o">=</span> <span class="kc">False</span>
                        <span class="k">break</span>

                    <span class="c1"># check that groups are all cliques</span>
                    <span class="k">for</span> <span class="n">g</span> <span class="ow">in</span> <span class="n">groups</span><span class="p">:</span>
                        <span class="k">if</span> <span class="ow">not</span> <span class="n">np</span><span class="o">.</span><span class="n">all</span><span class="p">(</span><span class="n">groups</span><span class="p">[</span><span class="n">g</span><span class="p">][:,</span> <span class="n">g</span><span class="p">]):</span>
                            <span class="n">valid</span> <span class="o">=</span> <span class="kc">False</span>
                            <span class="k">break</span>
                    <span class="k">if</span> <span class="ow">not</span> <span class="n">valid</span><span class="p">:</span>
                        <span class="k">break</span>

                    <span class="c1"># add the new sites, averaging positions</span>
                    <span class="n">added</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">gsites</span><span class="p">))</span>
                    <span class="n">new_fcoords</span> <span class="o">=</span> <span class="n">all_frac</span> <span class="o">%</span> <span class="mi">1</span>
                    <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">group</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">groups</span><span class="p">):</span>
                        <span class="k">if</span> <span class="ow">not</span> <span class="n">added</span><span class="p">[</span><span class="n">i</span><span class="p">]:</span>
                            <span class="n">added</span><span class="p">[</span><span class="n">group</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
                            <span class="n">inds</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">group</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
                            <span class="n">coords</span> <span class="o">=</span> <span class="n">new_fcoords</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span>
                            <span class="k">for</span> <span class="n">n</span><span class="p">,</span> <span class="n">j</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">inds</span><span class="p">[</span><span class="mi">1</span><span class="p">:]):</span>
                                <span class="n">offset</span> <span class="o">=</span> <span class="n">new_fcoords</span><span class="p">[</span><span class="n">j</span><span class="p">]</span> <span class="o">-</span> <span class="n">coords</span>
                                <span class="n">coords</span> <span class="o">+=</span> <span class="p">(</span><span class="n">offset</span> <span class="o">-</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">offset</span><span class="p">))</span> <span class="o">/</span> <span class="p">(</span><span class="n">n</span> <span class="o">+</span> <span class="mi">2</span><span class="p">)</span>
                            <span class="n">new_sp</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">gsites</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span><span class="o">.</span><span class="n">species</span><span class="p">)</span>
                            <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">gsites</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span><span class="o">.</span><span class="n">properties</span><span class="p">:</span>
                                <span class="n">new_props</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">gsites</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="n">k</span><span class="p">])</span>
                            <span class="n">new_coords</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>

                <span class="k">if</span> <span class="n">valid</span><span class="p">:</span>
                    <span class="n">inv_m</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">inv</span><span class="p">(</span><span class="n">m</span><span class="p">)</span>
                    <span class="n">new_l</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">inv_m</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">matrix</span><span class="p">))</span>
                    <span class="n">s</span> <span class="o">=</span> <span class="n">Structure</span><span class="p">(</span><span class="n">new_l</span><span class="p">,</span> <span class="n">new_sp</span><span class="p">,</span> <span class="n">new_coords</span><span class="p">,</span>
                                  <span class="n">site_properties</span><span class="o">=</span><span class="n">new_props</span><span class="p">,</span>
                                  <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>

                    <span class="c1"># Default behavior</span>
                    <span class="n">p</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get_primitive_structure</span><span class="p">(</span>
                        <span class="n">tolerance</span><span class="o">=</span><span class="n">tolerance</span><span class="p">,</span> <span class="n">use_site_props</span><span class="o">=</span><span class="n">use_site_props</span><span class="p">,</span>
                        <span class="n">constrain_latt</span><span class="o">=</span><span class="n">constrain_latt</span>
                    <span class="p">)</span><span class="o">.</span><span class="n">get_reduced_structure</span><span class="p">()</span>
                    <span class="k">if</span> <span class="ow">not</span> <span class="n">constrain_latt</span><span class="p">:</span>
                        <span class="k">return</span> <span class="n">p</span>

                    <span class="c1"># Only return primitive structures that</span>
                    <span class="c1"># satisfy the restriction condition</span>
                    <span class="n">p_latt</span><span class="p">,</span> <span class="n">s_latt</span> <span class="o">=</span> <span class="n">p</span><span class="o">.</span><span class="n">lattice</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span>
                    <span class="k">if</span> <span class="nb">type</span><span class="p">(</span><span class="n">constrain_latt</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;list&quot;</span><span class="p">:</span>
                        <span class="k">if</span> <span class="nb">all</span><span class="p">([</span><span class="nb">getattr</span><span class="p">(</span><span class="n">p_latt</span><span class="p">,</span> <span class="n">p</span><span class="p">)</span> <span class="o">==</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">s_latt</span><span class="p">,</span> <span class="n">p</span><span class="p">)</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">constrain_latt</span><span class="p">]):</span>
                            <span class="k">return</span> <span class="n">p</span>
                    <span class="k">elif</span> <span class="nb">type</span><span class="p">(</span><span class="n">constrain_latt</span><span class="p">)</span><span class="o">.</span><span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;dict&quot;</span><span class="p">:</span>
                        <span class="k">if</span> <span class="nb">all</span><span class="p">([</span><span class="nb">getattr</span><span class="p">(</span><span class="n">p_latt</span><span class="p">,</span> <span class="n">p</span><span class="p">)</span> <span class="o">==</span> <span class="n">constrain_latt</span><span class="p">[</span><span class="n">p</span><span class="p">]</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">constrain_latt</span><span class="o">.</span><span class="n">keys</span><span class="p">()]):</span>
                            <span class="k">return</span> <span class="n">p</span>

        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span></div>

    <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">outs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Structure Summary&quot;</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="p">)]</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">:</span>
            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">&gt;=</span> <span class="mi">0</span><span class="p">:</span>
                <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;Overall Charge: +</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">))</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;Overall Charge: -</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">))</span>
        <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="nb">repr</span><span class="p">(</span><span class="n">s</span><span class="p">))</span>
        <span class="k">return</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outs</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">outs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Full Formula (</span><span class="si">{s}</span><span class="s2">)&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">s</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">formula</span><span class="p">),</span>
                <span class="s2">&quot;Reduced Formula: </span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">reduced_formula</span><span class="p">)]</span>

        <span class="k">def</span> <span class="nf">to_s</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
            <span class="k">return</span> <span class="s2">&quot;</span><span class="si">%0.6f</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="n">x</span>
        <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;abc   : &quot;</span> <span class="o">+</span> <span class="s2">&quot; &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">to_s</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="o">.</span><span class="n">rjust</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
                                           <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">abc</span><span class="p">]))</span>
        <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;angles: &quot;</span> <span class="o">+</span> <span class="s2">&quot; &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="n">to_s</span><span class="p">(</span><span class="n">i</span><span class="p">)</span><span class="o">.</span><span class="n">rjust</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
                                           <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="o">.</span><span class="n">angles</span><span class="p">]))</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">:</span>
            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">&gt;=</span> <span class="mi">0</span><span class="p">:</span>
                <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;Overall Charge: +</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">))</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;Overall Charge: -</span><span class="si">{}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">))</span>
        <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot;Sites (</span><span class="si">{i}</span><span class="s2">)&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)))</span>
        <span class="n">data</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">props</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span>
        <span class="n">keys</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">props</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
            <span class="n">row</span> <span class="o">=</span> <span class="p">[</span><span class="nb">str</span><span class="p">(</span><span class="n">i</span><span class="p">),</span> <span class="n">site</span><span class="o">.</span><span class="n">species_string</span><span class="p">]</span>
            <span class="n">row</span><span class="o">.</span><span class="n">extend</span><span class="p">([</span><span class="n">to_s</span><span class="p">(</span><span class="n">j</span><span class="p">)</span> <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">])</span>
            <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">keys</span><span class="p">:</span>
                <span class="n">row</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">props</span><span class="p">[</span><span class="n">k</span><span class="p">][</span><span class="n">i</span><span class="p">])</span>
            <span class="n">data</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
        <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">tabulate</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;#&quot;</span><span class="p">,</span> <span class="s2">&quot;SP&quot;</span><span class="p">,</span> <span class="s2">&quot;a&quot;</span><span class="p">,</span> <span class="s2">&quot;b&quot;</span><span class="p">,</span> <span class="s2">&quot;c&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="n">keys</span><span class="p">,</span>
                             <span class="p">))</span>
        <span class="k">return</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outs</span><span class="p">)</span>

<div class="viewcode-block" id="IStructure.as_dict"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.as_dict">[docs]</a>    <span class="k">def</span> <span class="nf">as_dict</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">verbosity</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Dict representation of Structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            verbosity (int): Verbosity level. Default of 1 includes both</span>
<span class="sd">                direct and cartesian coordinates for all sites, lattice</span>
<span class="sd">                parameters, etc. Useful for reading and for insertion into a</span>
<span class="sd">                database. Set to 0 for an extremely lightweight version</span>
<span class="sd">                that only includes sufficient information to reconstruct the</span>
<span class="sd">                object.</span>
<span class="sd">            fmt (str): Specifies a format for the dict. Defaults to None,</span>
<span class="sd">                which is the default format used in pymatgen. Other options</span>
<span class="sd">                include &quot;abivars&quot;.</span>
<span class="sd">            **kwargs: Allow passing of other kwargs needed for certain</span>
<span class="sd">            formats, e.g., &quot;abivars&quot;.</span>

<span class="sd">        Returns:</span>
<span class="sd">            JSON serializable dict representation.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;abivars&quot;</span><span class="p">:</span>
            <span class="sd">&quot;&quot;&quot;Returns a dictionary with the ABINIT variables.&quot;&quot;&quot;</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.abinit.abiobjects</span> <span class="kn">import</span> <span class="n">structure_to_abivars</span>
            <span class="k">return</span> <span class="n">structure_to_abivars</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>

        <span class="n">latt_dict</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">as_dict</span><span class="p">(</span><span class="n">verbosity</span><span class="o">=</span><span class="n">verbosity</span><span class="p">)</span>
        <span class="k">del</span> <span class="n">latt_dict</span><span class="p">[</span><span class="s2">&quot;@module&quot;</span><span class="p">]</span>
        <span class="k">del</span> <span class="n">latt_dict</span><span class="p">[</span><span class="s2">&quot;@class&quot;</span><span class="p">]</span>

        <span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;@module&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__module__</span><span class="p">,</span>
             <span class="s2">&quot;@class&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="p">,</span>
             <span class="s2">&quot;charge&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span>
             <span class="s2">&quot;lattice&quot;</span><span class="p">:</span> <span class="n">latt_dict</span><span class="p">,</span> <span class="s2">&quot;sites&quot;</span><span class="p">:</span> <span class="p">[]}</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">site_dict</span> <span class="o">=</span> <span class="n">site</span><span class="o">.</span><span class="n">as_dict</span><span class="p">(</span><span class="n">verbosity</span><span class="o">=</span><span class="n">verbosity</span><span class="p">)</span>
            <span class="k">del</span> <span class="n">site_dict</span><span class="p">[</span><span class="s2">&quot;lattice&quot;</span><span class="p">]</span>
            <span class="k">del</span> <span class="n">site_dict</span><span class="p">[</span><span class="s2">&quot;@module&quot;</span><span class="p">]</span>
            <span class="k">del</span> <span class="n">site_dict</span><span class="p">[</span><span class="s2">&quot;@class&quot;</span><span class="p">]</span>
            <span class="n">d</span><span class="p">[</span><span class="s2">&quot;sites&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site_dict</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">d</span></div>

<div class="viewcode-block" id="IStructure.as_dataframe"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.as_dataframe">[docs]</a>    <span class="k">def</span> <span class="nf">as_dataframe</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns a Pandas dataframe of the sites. Structure level attributes are stored in DataFrame.attrs. Example:</span>

<span class="sd">        Species    a    b             c    x             y             z  magmom</span>
<span class="sd">        0    (Si)  0.0  0.0  0.000000e+00  0.0  0.000000e+00  0.000000e+00       5</span>
<span class="sd">        1    (Si)  0.0  0.0  1.000000e-07  0.0 -2.217138e-07  3.135509e-07      -5</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">data</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">site_properties</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span>
        <span class="n">prop_keys</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">site_properties</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">row</span> <span class="o">=</span> <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">]</span> <span class="o">+</span> <span class="nb">list</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">)</span> <span class="o">+</span> <span class="nb">list</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">)</span>
            <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">prop_keys</span><span class="p">:</span>
                <span class="n">row</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">k</span><span class="p">))</span>
            <span class="n">data</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
        <span class="kn">import</span> <span class="nn">pandas</span> <span class="k">as</span> <span class="nn">pd</span>
        <span class="n">df</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">columns</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;Species&quot;</span><span class="p">,</span> <span class="s2">&quot;a&quot;</span><span class="p">,</span> <span class="s2">&quot;b&quot;</span><span class="p">,</span> <span class="s2">&quot;c&quot;</span><span class="p">,</span> <span class="s2">&quot;x&quot;</span><span class="p">,</span> <span class="s2">&quot;y&quot;</span><span class="p">,</span> <span class="s2">&quot;z&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="n">prop_keys</span><span class="p">)</span>
        <span class="n">df</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s2">&quot;Reduced Formula&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">reduced_formula</span>
        <span class="n">df</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s2">&quot;Lattice&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span>
        <span class="k">return</span> <span class="n">df</span></div>

<div class="viewcode-block" id="IStructure.from_dict"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.from_dict">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_dict</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">d</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reconstitute a Structure object from a dict representation of Structure</span>
<span class="sd">        created using as_dict().</span>

<span class="sd">        Args:</span>
<span class="sd">            d (dict): Dict representation of structure.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Structure object</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;abivars&quot;</span><span class="p">:</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.abinit.abiobjects</span> <span class="kn">import</span> <span class="n">structure_from_abivars</span>
            <span class="k">return</span> <span class="n">structure_from_abivars</span><span class="p">(</span><span class="bp">cls</span><span class="o">=</span><span class="bp">cls</span><span class="p">,</span> <span class="o">**</span><span class="n">d</span><span class="p">)</span>

        <span class="n">lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">d</span><span class="p">[</span><span class="s2">&quot;lattice&quot;</span><span class="p">])</span>
        <span class="n">sites</span> <span class="o">=</span> <span class="p">[</span><span class="n">PeriodicSite</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">sd</span><span class="p">,</span> <span class="n">lattice</span><span class="p">)</span> <span class="k">for</span> <span class="n">sd</span> <span class="ow">in</span> <span class="n">d</span><span class="p">[</span><span class="s2">&quot;sites&quot;</span><span class="p">]]</span>
        <span class="n">charge</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;charge&quot;</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">sites</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.to"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.to">[docs]</a>    <span class="k">def</span> <span class="nf">to</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="sa">r</span><span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Outputs the structure to a file or string.</span>

<span class="sd">        Args:</span>
<span class="sd">            fmt (str): Format to output to. Defaults to JSON unless filename</span>
<span class="sd">                is provided. If fmt is specifies, it overrides whatever the</span>
<span class="sd">                filename is. Options include &quot;cif&quot;, &quot;poscar&quot;, &quot;cssr&quot;, &quot;json&quot;.</span>
<span class="sd">                Non-case sensitive.</span>
<span class="sd">            filename (str): If provided, output will be written to a file. If</span>
<span class="sd">                fmt is not specified, the format is determined from the</span>
<span class="sd">                filename. Defaults is None, i.e. string output.</span>
<span class="sd">            **kwargs: Kwargs passthru to relevant methods. E.g., This allows</span>
<span class="sd">                the passing of parameters like symprec to the</span>
<span class="sd">                CifWriter.__init__ method for generation of symmetric cifs.</span>

<span class="sd">        Returns:</span>
<span class="sd">            (str) if filename is None. None otherwise.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="n">filename</span> <span class="ow">or</span> <span class="s2">&quot;&quot;</span>
        <span class="n">fmt</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span> <span class="k">if</span> <span class="n">fmt</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">fmt</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
        <span class="n">fname</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>

        <span class="k">if</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;cif&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.cif*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.cif</span> <span class="kn">import</span> <span class="n">CifWriter</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">CifWriter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;mcif&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.mcif*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.cif</span> <span class="kn">import</span> <span class="n">CifWriter</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">CifWriter</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">write_magmoms</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;poscar&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*POSCAR*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.vasp</span> <span class="kn">import</span> <span class="n">Poscar</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">Poscar</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;cssr&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.cssr*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.cssr</span> <span class="kn">import</span> <span class="n">Cssr</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">Cssr</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;json&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.json&quot;</span><span class="p">):</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">())</span>
            <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
                <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s2">&quot;wt&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="n">s</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">s</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;xsf&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.xsf*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.xcrysden</span> <span class="kn">import</span> <span class="n">XSF</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">XSF</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">to_string</span><span class="p">()</span>
            <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
                <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;wt&quot;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf8&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">s</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s1">&#39;mcsqs&#39;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*rndstr.in*&quot;</span><span class="p">)</span> \
                <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*lat.in*&quot;</span><span class="p">)</span> \
                <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*bestsqs*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.atat</span> <span class="kn">import</span> <span class="n">Mcsqs</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Mcsqs</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">to_string</span><span class="p">()</span>
            <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
                <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;wt&quot;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;ascii&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">s</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">s</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s1">&#39;prismatic&#39;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*prismatic*&quot;</span><span class="p">):</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.prismatic</span> <span class="kn">import</span> <span class="n">Prismatic</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Prismatic</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">to_string</span><span class="p">()</span>
            <span class="k">return</span> <span class="n">s</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;yaml&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.yaml*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.yml*&quot;</span><span class="p">):</span>
            <span class="kn">import</span> <span class="nn">ruamel.yaml</span> <span class="k">as</span> <span class="nn">yaml</span>
            <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
                <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s2">&quot;wt&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="n">yaml</span><span class="o">.</span><span class="n">safe_dump</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">(),</span> <span class="n">f</span><span class="p">)</span>
                <span class="k">return</span> <span class="kc">None</span>
            <span class="k">return</span> <span class="n">yaml</span><span class="o">.</span><span class="n">safe_dump</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">())</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Invalid format: `</span><span class="si">%s</span><span class="s2">`&quot;</span> <span class="o">%</span> <span class="nb">str</span><span class="p">(</span><span class="n">fmt</span><span class="p">))</span>

        <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
            <span class="n">writer</span><span class="o">.</span><span class="n">write_file</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
            <span class="k">return</span> <span class="kc">None</span>
        <span class="k">return</span> <span class="n">writer</span><span class="o">.</span><span class="fm">__str__</span><span class="p">()</span></div>

<div class="viewcode-block" id="IStructure.from_str"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.from_str">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_str</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">input_string</span><span class="p">,</span> <span class="n">fmt</span><span class="p">,</span> <span class="n">primitive</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
                 <span class="n">merge_tol</span><span class="o">=</span><span class="mf">0.0</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reads a structure from a string.</span>

<span class="sd">        Args:</span>
<span class="sd">            input_string (str): String to parse.</span>
<span class="sd">            fmt (str): A format specification.</span>
<span class="sd">            primitive (bool): Whether to find a primitive cell. Defaults to</span>
<span class="sd">                False.</span>
<span class="sd">            sort (bool): Whether to sort the sites in accordance to the default</span>
<span class="sd">                ordering criteria, i.e., electronegativity.</span>
<span class="sd">            merge_tol (float): If this is some positive number, sites that</span>
<span class="sd">                are within merge_tol from each other will be merged. Usually</span>
<span class="sd">                0.01 should be enough to deal with common numerical issues.</span>

<span class="sd">        Returns:</span>
<span class="sd">            IStructure / Structure</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.cif</span> <span class="kn">import</span> <span class="n">CifParser</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.vasp</span> <span class="kn">import</span> <span class="n">Poscar</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.cssr</span> <span class="kn">import</span> <span class="n">Cssr</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.xcrysden</span> <span class="kn">import</span> <span class="n">XSF</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.atat</span> <span class="kn">import</span> <span class="n">Mcsqs</span>
        <span class="n">fmt</span> <span class="o">=</span> <span class="n">fmt</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;cif&quot;</span><span class="p">:</span>
            <span class="n">parser</span> <span class="o">=</span> <span class="n">CifParser</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">get_structures</span><span class="p">(</span><span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;poscar&quot;</span><span class="p">:</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Poscar</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">,</span> <span class="kc">False</span><span class="p">,</span>
                                   <span class="n">read_velocities</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span><span class="o">.</span><span class="n">structure</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;cssr&quot;</span><span class="p">:</span>
            <span class="n">cssr</span> <span class="o">=</span> <span class="n">Cssr</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">cssr</span><span class="o">.</span><span class="n">structure</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;json&quot;</span><span class="p">:</span>
            <span class="n">d</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Structure</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;yaml&quot;</span><span class="p">:</span>
            <span class="kn">import</span> <span class="nn">ruamel.yaml</span> <span class="k">as</span> <span class="nn">yaml</span>
            <span class="n">d</span> <span class="o">=</span> <span class="n">yaml</span><span class="o">.</span><span class="n">safe_load</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Structure</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;xsf&quot;</span><span class="p">:</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">XSF</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span><span class="o">.</span><span class="n">structure</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;mcsqs&quot;</span><span class="p">:</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Mcsqs</span><span class="o">.</span><span class="n">structure_from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Unrecognized format `</span><span class="si">%s</span><span class="s2">`!&quot;</span> <span class="o">%</span> <span class="n">fmt</span><span class="p">)</span>

        <span class="k">if</span> <span class="n">sort</span><span class="p">:</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get_sorted_structure</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">merge_tol</span><span class="p">:</span>
            <span class="n">s</span><span class="o">.</span><span class="n">merge_sites</span><span class="p">(</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">s</span><span class="p">)</span></div>

<div class="viewcode-block" id="IStructure.from_file"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IStructure.from_file">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_file</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">filename</span><span class="p">,</span> <span class="n">primitive</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">merge_tol</span><span class="o">=</span><span class="mf">0.0</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reads a structure from a file. For example, anything ending in</span>
<span class="sd">        a &quot;cif&quot; is assumed to be a Crystallographic Information Format file.</span>
<span class="sd">        Supported formats include CIF, POSCAR/CONTCAR, CHGCAR, LOCPOT,</span>
<span class="sd">        vasprun.xml, CSSR, Netcdf and pymatgen&#39;s JSON serialized structures.</span>

<span class="sd">        Args:</span>
<span class="sd">            filename (str): The filename to read from.</span>
<span class="sd">            primitive (bool): Whether to convert to a primitive cell</span>
<span class="sd">                Only available for cifs. Defaults to False.</span>
<span class="sd">            sort (bool): Whether to sort sites. Default to False.</span>
<span class="sd">            merge_tol (float): If this is some positive number, sites that</span>
<span class="sd">                are within merge_tol from each other will be merged. Usually</span>
<span class="sd">                0.01 should be enough to deal with common numerical issues.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">filename</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s2">&quot;.nc&quot;</span><span class="p">):</span>
            <span class="c1"># Read Structure from a netcdf file.</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.abinit.netcdf</span> <span class="kn">import</span> <span class="n">structure_from_ncdata</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">structure_from_ncdata</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="bp">cls</span><span class="o">=</span><span class="bp">cls</span><span class="p">)</span>
            <span class="k">if</span> <span class="n">sort</span><span class="p">:</span>
                <span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get_sorted_structure</span><span class="p">()</span>
            <span class="k">return</span> <span class="n">s</span>

        <span class="kn">from</span> <span class="nn">pymatgen.io.lmto</span> <span class="kn">import</span> <span class="n">LMTOCtrl</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.vasp</span> <span class="kn">import</span> <span class="n">Vasprun</span><span class="p">,</span> <span class="n">Chgcar</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.exciting</span> <span class="kn">import</span> <span class="n">ExcitingInput</span>
        <span class="n">fname</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
        <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s2">&quot;rt&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
            <span class="n">contents</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.cif*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.mcif*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;cif&quot;</span><span class="p">,</span>
                                <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                                <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*POSCAR*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*CONTCAR*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.vasp&quot;</span><span class="p">):</span>
            <span class="n">s</span> <span class="o">=</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;poscar&quot;</span><span class="p">,</span>
                             <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                             <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>

        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;CHGCAR*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;LOCPOT*&quot;</span><span class="p">):</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Chgcar</span><span class="o">.</span><span class="n">from_file</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span><span class="o">.</span><span class="n">structure</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;vasprun*.xml*&quot;</span><span class="p">):</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">Vasprun</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span><span class="o">.</span><span class="n">final_structure</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.cssr*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;cssr&quot;</span><span class="p">,</span>
                                <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                                <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.json*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.mson*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;json&quot;</span><span class="p">,</span>
                                <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                                <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.yaml*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;yaml&quot;</span><span class="p">,</span>
                                <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                                <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.xsf&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;xsf&quot;</span><span class="p">,</span>
                                <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                                <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;input*.xml&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">ExcitingInput</span><span class="o">.</span><span class="n">from_file</span><span class="p">(</span><span class="n">fname</span><span class="p">)</span><span class="o">.</span><span class="n">structure</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*rndstr.in*&quot;</span><span class="p">)</span> \
                <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*lat.in*&quot;</span><span class="p">)</span> \
                <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*bestsqs*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;mcsqs&quot;</span><span class="p">,</span>
                                <span class="n">primitive</span><span class="o">=</span><span class="n">primitive</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="n">sort</span><span class="p">,</span>
                                <span class="n">merge_tol</span><span class="o">=</span><span class="n">merge_tol</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;CTRL*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="n">LMTOCtrl</span><span class="o">.</span><span class="n">from_file</span><span class="p">(</span><span class="n">filename</span><span class="o">=</span><span class="n">filename</span><span class="p">)</span><span class="o">.</span><span class="n">structure</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Unrecognized file extension!&quot;</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">sort</span><span class="p">:</span>
            <span class="n">s</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">get_sorted_structure</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">merge_tol</span><span class="p">:</span>
            <span class="n">s</span><span class="o">.</span><span class="n">merge_sites</span><span class="p">(</span><span class="n">merge_tol</span><span class="p">)</span>

        <span class="n">s</span><span class="o">.</span><span class="vm">__class__</span> <span class="o">=</span> <span class="bp">cls</span>
        <span class="k">return</span> <span class="n">s</span></div></div>


<div class="viewcode-block" id="IMolecule"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule">[docs]</a><span class="k">class</span> <span class="nc">IMolecule</span><span class="p">(</span><span class="n">SiteCollection</span><span class="p">,</span> <span class="n">MSONable</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Basic immutable Molecule object without periodicity. Essentially a</span>
<span class="sd">    sequence of sites. IMolecule is made to be immutable so that they can</span>
<span class="sd">    function as keys in a dict. For a mutable molecule,</span>
<span class="sd">    use the :class:Molecule.</span>

<span class="sd">    Molecule extends Sequence and Hashable, which means that in many cases,</span>
<span class="sd">    it can be used like any Python sequence. Iterating through a molecule is</span>
<span class="sd">    equivalent to going through the sites in sequence.</span>
<span class="sd">    &quot;&quot;&quot;</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
                 <span class="n">species</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">,</span> <span class="n">Composition</span><span class="p">]],</span>
                 <span class="n">coords</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">float</span><span class="p">]],</span>
                 <span class="n">charge</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span>
                 <span class="n">spin_multiplicity</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="n">validate_proximity</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">site_properties</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Creates a Molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            species: list of atomic species. Possible kinds of input include a</span>
<span class="sd">                list of dict of elements/species and occupancies, a List of</span>
<span class="sd">                elements/specie specified as actual Element/Specie, Strings</span>
<span class="sd">                (&quot;Fe&quot;, &quot;Fe2+&quot;) or atomic numbers (1,56).</span>
<span class="sd">            coords (3x1 array): list of cartesian coordinates of each species.</span>
<span class="sd">            charge (float): Charge for the molecule. Defaults to 0.</span>
<span class="sd">            spin_multiplicity (int): Spin multiplicity for molecule.</span>
<span class="sd">                Defaults to None, which means that the spin multiplicity is</span>
<span class="sd">                set to 1 if the molecule has no unpaired electrons and to 2</span>
<span class="sd">                if there are unpaired electrons.</span>
<span class="sd">            validate_proximity (bool): Whether to check if there are sites</span>
<span class="sd">                that are less than 1 Ang apart. Defaults to False.</span>
<span class="sd">            site_properties (dict): Properties associated with the sites as</span>
<span class="sd">                a dict of sequences, e.g., {&quot;magmom&quot;:[5,5,5,5]}. The</span>
<span class="sd">                sequences have to be the same length as the atomic species</span>
<span class="sd">                and fractional_coords. Defaults to None for no properties.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">):</span>
            <span class="k">raise</span> <span class="n">StructureError</span><span class="p">((</span><span class="s2">&quot;The list of atomic species must be of the&quot;</span><span class="p">,</span>
                                  <span class="s2">&quot; same length as the list of fractional &quot;</span><span class="p">,</span>
                                  <span class="s2">&quot;coordinates.&quot;</span><span class="p">))</span>

        <span class="n">sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">species</span><span class="p">)):</span>
            <span class="n">prop</span> <span class="o">=</span> <span class="kc">None</span>
            <span class="k">if</span> <span class="n">site_properties</span><span class="p">:</span>
                <span class="n">prop</span> <span class="o">=</span> <span class="p">{</span><span class="n">k</span><span class="p">:</span> <span class="n">v</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">site_properties</span><span class="o">.</span><span class="n">items</span><span class="p">()}</span>
            <span class="n">sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Site</span><span class="p">(</span><span class="n">species</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">coords</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">properties</span><span class="o">=</span><span class="n">prop</span><span class="p">))</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="nb">tuple</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">validate_proximity</span> <span class="ow">and</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">is_valid</span><span class="p">():</span>
            <span class="k">raise</span> <span class="n">StructureError</span><span class="p">((</span><span class="s2">&quot;Molecule contains sites that are &quot;</span><span class="p">,</span>
                                  <span class="s2">&quot;less than 0.01 Angstrom apart!&quot;</span><span class="p">))</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">=</span> <span class="n">charge</span>
        <span class="n">nelectrons</span> <span class="o">=</span> <span class="mf">0.0</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">amt</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">):</span>
                    <span class="n">nelectrons</span> <span class="o">+=</span> <span class="n">sp</span><span class="o">.</span><span class="n">Z</span> <span class="o">*</span> <span class="n">amt</span>  <span class="c1"># type: ignore</span>
        <span class="n">nelectrons</span> <span class="o">-=</span> <span class="n">charge</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_nelectrons</span> <span class="o">=</span> <span class="n">nelectrons</span>
        <span class="k">if</span> <span class="n">spin_multiplicity</span><span class="p">:</span>
            <span class="k">if</span> <span class="p">(</span><span class="n">nelectrons</span> <span class="o">+</span> <span class="n">spin_multiplicity</span><span class="p">)</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">!=</span> <span class="mi">1</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                    <span class="s2">&quot;Charge of </span><span class="si">%d</span><span class="s2"> and spin multiplicity of </span><span class="si">%d</span><span class="s2"> is&quot;</span>
                    <span class="s2">&quot; not possible for this molecule&quot;</span> <span class="o">%</span>
                    <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span> <span class="n">spin_multiplicity</span><span class="p">))</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span> <span class="o">=</span> <span class="n">spin_multiplicity</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span> <span class="o">=</span> <span class="mi">1</span> <span class="k">if</span> <span class="n">nelectrons</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="k">else</span> <span class="mi">2</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">charge</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Charge of molecule</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">spin_multiplicity</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Spin multiplicity of molecule.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">nelectrons</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Number of electrons in the molecule.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_nelectrons</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">center_of_mass</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Center of mass of molecule.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">center</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
        <span class="n">total_weight</span> <span class="o">=</span> <span class="mi">0</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">wt</span> <span class="o">=</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">weight</span>
            <span class="n">center</span> <span class="o">+=</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="o">*</span> <span class="n">wt</span>
            <span class="n">total_weight</span> <span class="o">+=</span> <span class="n">wt</span>
        <span class="k">return</span> <span class="n">center</span> <span class="o">/</span> <span class="n">total_weight</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">sites</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns a tuple of sites in the Molecule.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span>

<div class="viewcode-block" id="IMolecule.from_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.from_sites">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_sites</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">sites</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">spin_multiplicity</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
                   <span class="n">validate_proximity</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Convenience constructor to make a Molecule from a list of sites.</span>

<span class="sd">        Args:</span>
<span class="sd">            sites ([Site]): Sequence of Sites.</span>
<span class="sd">            charge (int): Charge of molecule. Defaults to 0.</span>
<span class="sd">            spin_multiplicity (int): Spin multicipity. Defaults to None,</span>
<span class="sd">                in which it is determined automatically.</span>
<span class="sd">            validate_proximity (bool): Whether to check that atoms are too</span>
<span class="sd">                close.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">props</span> <span class="o">=</span> <span class="n">collections</span><span class="o">.</span><span class="n">defaultdict</span><span class="p">(</span><span class="nb">list</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="n">props</span><span class="p">[</span><span class="n">k</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">v</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">cls</span><span class="p">([</span><span class="n">site</span><span class="o">.</span><span class="n">species</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">],</span>
                   <span class="p">[</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">],</span>
                   <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">,</span> <span class="n">spin_multiplicity</span><span class="o">=</span><span class="n">spin_multiplicity</span><span class="p">,</span>
                   <span class="n">validate_proximity</span><span class="o">=</span><span class="n">validate_proximity</span><span class="p">,</span>
                   <span class="n">site_properties</span><span class="o">=</span><span class="n">props</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.break_bond"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.break_bond">[docs]</a>    <span class="k">def</span> <span class="nf">break_bond</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ind1</span><span class="p">,</span> <span class="n">ind2</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="mf">0.2</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns two molecules based on breaking the bond between atoms at index</span>
<span class="sd">        ind1 and ind2.</span>

<span class="sd">        Args:</span>
<span class="sd">            ind1 (int): Index of first site.</span>
<span class="sd">            ind2 (int): Index of second site.</span>
<span class="sd">            tol (float): Relative tolerance to test. Basically, the code</span>
<span class="sd">                checks if the distance between the sites is less than (1 +</span>
<span class="sd">                tol) * typical bond distances. Defaults to 0.2, i.e.,</span>
<span class="sd">                20% longer.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Two Molecule objects representing the two clusters formed from</span>
<span class="sd">            breaking the bond.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">sites</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span>
        <span class="n">clusters</span> <span class="o">=</span> <span class="p">[[</span><span class="n">sites</span><span class="p">[</span><span class="n">ind1</span><span class="p">]],</span> <span class="p">[</span><span class="n">sites</span><span class="p">[</span><span class="n">ind2</span><span class="p">]]]</span>

        <span class="n">sites</span> <span class="o">=</span> <span class="p">[</span><span class="n">site</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span> <span class="k">if</span> <span class="n">i</span> <span class="ow">not</span> <span class="ow">in</span> <span class="p">(</span><span class="n">ind1</span><span class="p">,</span> <span class="n">ind2</span><span class="p">)]</span>

        <span class="k">def</span> <span class="nf">belongs_to_cluster</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">cluster</span><span class="p">):</span>
            <span class="k">for</span> <span class="n">test_site</span> <span class="ow">in</span> <span class="n">cluster</span><span class="p">:</span>
                <span class="k">if</span> <span class="n">CovalentBond</span><span class="o">.</span><span class="n">is_bonded</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">test_site</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="n">tol</span><span class="p">):</span>
                    <span class="k">return</span> <span class="kc">True</span>
            <span class="k">return</span> <span class="kc">False</span>

        <span class="k">while</span> <span class="nb">len</span><span class="p">(</span><span class="n">sites</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
            <span class="n">unmatched</span> <span class="o">=</span> <span class="p">[]</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">sites</span><span class="p">:</span>
                <span class="k">for</span> <span class="n">cluster</span> <span class="ow">in</span> <span class="n">clusters</span><span class="p">:</span>
                    <span class="k">if</span> <span class="n">belongs_to_cluster</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">cluster</span><span class="p">):</span>
                        <span class="n">cluster</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site</span><span class="p">)</span>
                        <span class="k">break</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="n">unmatched</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site</span><span class="p">)</span>

            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">unmatched</span><span class="p">)</span> <span class="o">==</span> <span class="nb">len</span><span class="p">(</span><span class="n">sites</span><span class="p">):</span>
                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Not all sites are matched!&quot;</span><span class="p">)</span>
            <span class="n">sites</span> <span class="o">=</span> <span class="n">unmatched</span>

        <span class="k">return</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">cluster</span><span class="p">)</span>
                <span class="k">for</span> <span class="n">cluster</span> <span class="ow">in</span> <span class="n">clusters</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.get_covalent_bonds"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_covalent_bonds">[docs]</a>    <span class="k">def</span> <span class="nf">get_covalent_bonds</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="mf">0.2</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Determines the covalent bonds in a molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            tol (float): The tol to determine bonds in a structure. See</span>
<span class="sd">                CovalentBond.is_bonded.</span>

<span class="sd">        Returns:</span>
<span class="sd">            List of bonds</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">bonds</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">site1</span><span class="p">,</span> <span class="n">site2</span> <span class="ow">in</span> <span class="n">itertools</span><span class="o">.</span><span class="n">combinations</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">,</span> <span class="mi">2</span><span class="p">):</span>
            <span class="k">if</span> <span class="n">CovalentBond</span><span class="o">.</span><span class="n">is_bonded</span><span class="p">(</span><span class="n">site1</span><span class="p">,</span> <span class="n">site2</span><span class="p">,</span> <span class="n">tol</span><span class="p">):</span>
                <span class="n">bonds</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">CovalentBond</span><span class="p">(</span><span class="n">site1</span><span class="p">,</span> <span class="n">site2</span><span class="p">))</span>
        <span class="k">return</span> <span class="n">bonds</span></div>

    <span class="k">def</span> <span class="fm">__eq__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">other</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">!=</span> <span class="nb">len</span><span class="p">(</span><span class="n">other</span><span class="p">):</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">charge</span> <span class="o">!=</span> <span class="n">other</span><span class="o">.</span><span class="n">charge</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">spin_multiplicity</span> <span class="o">!=</span> <span class="n">other</span><span class="o">.</span><span class="n">spin_multiplicity</span><span class="p">:</span>
            <span class="k">return</span> <span class="kc">False</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="k">if</span> <span class="n">site</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">other</span><span class="p">:</span>
                <span class="k">return</span> <span class="kc">False</span>
        <span class="k">return</span> <span class="kc">True</span>

    <span class="k">def</span> <span class="fm">__ne__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
        <span class="k">return</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="fm">__eq__</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__hash__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="c1"># For now, just use the composition hash code.</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="fm">__hash__</span><span class="p">()</span>

    <span class="k">def</span> <span class="fm">__repr__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">outs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Molecule Summary&quot;</span><span class="p">]</span>
        <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="fm">__repr__</span><span class="p">())</span>
        <span class="k">return</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outs</span><span class="p">)</span>

    <span class="k">def</span> <span class="fm">__str__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">outs</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;Full Formula (</span><span class="si">%s</span><span class="s2">)&quot;</span> <span class="o">%</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">formula</span><span class="p">,</span>
                <span class="s2">&quot;Reduced Formula: &quot;</span> <span class="o">+</span> <span class="bp">self</span><span class="o">.</span><span class="n">composition</span><span class="o">.</span><span class="n">reduced_formula</span><span class="p">,</span>
                <span class="s2">&quot;Charge = </span><span class="si">%s</span><span class="s2">, Spin Mult = </span><span class="si">%s</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="p">(</span>
                    <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span><span class="p">),</span>
                <span class="s2">&quot;Sites (</span><span class="si">%d</span><span class="s2">)&quot;</span> <span class="o">%</span> <span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">)]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
            <span class="n">outs</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s2">&quot; &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([</span><span class="nb">str</span><span class="p">(</span><span class="n">i</span><span class="p">),</span> <span class="n">site</span><span class="o">.</span><span class="n">species_string</span><span class="p">,</span>
                                  <span class="s2">&quot; &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">([(</span><span class="s2">&quot;</span><span class="si">%0.6f</span><span class="s2">&quot;</span> <span class="o">%</span> <span class="n">j</span><span class="p">)</span><span class="o">.</span><span class="n">rjust</span><span class="p">(</span><span class="mi">12</span><span class="p">)</span>
                                            <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">])]))</span>
        <span class="k">return</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outs</span><span class="p">)</span>

<div class="viewcode-block" id="IMolecule.as_dict"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.as_dict">[docs]</a>    <span class="k">def</span> <span class="nf">as_dict</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Json-serializable dict representation of Molecule</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;@module&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__module__</span><span class="p">,</span>
             <span class="s2">&quot;@class&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="vm">__name__</span><span class="p">,</span>
             <span class="s2">&quot;charge&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span>
             <span class="s2">&quot;spin_multiplicity&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span><span class="p">,</span>
             <span class="s2">&quot;sites&quot;</span><span class="p">:</span> <span class="p">[]}</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
            <span class="n">site_dict</span> <span class="o">=</span> <span class="n">site</span><span class="o">.</span><span class="n">as_dict</span><span class="p">()</span>
            <span class="k">del</span> <span class="n">site_dict</span><span class="p">[</span><span class="s2">&quot;@module&quot;</span><span class="p">]</span>
            <span class="k">del</span> <span class="n">site_dict</span><span class="p">[</span><span class="s2">&quot;@class&quot;</span><span class="p">]</span>
            <span class="n">d</span><span class="p">[</span><span class="s2">&quot;sites&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site_dict</span><span class="p">)</span>
        <span class="k">return</span> <span class="n">d</span></div>

<div class="viewcode-block" id="IMolecule.from_dict"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.from_dict">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_dict</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">d</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reconstitute a Molecule object from a dict representation created using</span>
<span class="sd">        as_dict().</span>

<span class="sd">        Args:</span>
<span class="sd">            d (dict): dict representation of Molecule.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Molecule object</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">sites</span> <span class="o">=</span> <span class="p">[</span><span class="n">Site</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">sd</span><span class="p">)</span> <span class="k">for</span> <span class="n">sd</span> <span class="ow">in</span> <span class="n">d</span><span class="p">[</span><span class="s2">&quot;sites&quot;</span><span class="p">]]</span>
        <span class="n">charge</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;charge&quot;</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
        <span class="n">spin_multiplicity</span> <span class="o">=</span> <span class="n">d</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;spin_multiplicity&quot;</span><span class="p">)</span>
        <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">sites</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">,</span> <span class="n">spin_multiplicity</span><span class="o">=</span><span class="n">spin_multiplicity</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.get_distance"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_distance">[docs]</a>    <span class="k">def</span> <span class="nf">get_distance</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get distance between site i and j.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int): Index of first site</span>
<span class="sd">            j (int): Index of second site</span>

<span class="sd">        Returns:</span>
<span class="sd">            Distance between the two sites.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">distance</span><span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">j</span><span class="p">])</span></div>

<div class="viewcode-block" id="IMolecule.get_sites_in_sphere"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_sites_in_sphere">[docs]</a>    <span class="k">def</span> <span class="nf">get_sites_in_sphere</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">pt</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Find all sites within a sphere from a point.</span>

<span class="sd">        Args:</span>
<span class="sd">            pt (3x1 array): Cartesian coordinates of center of sphere</span>
<span class="sd">            r (float): Radius of sphere.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [Neighbor] since most of the time, subsequent processing</span>
<span class="sd">            requires the distance.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">neighbors</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">):</span>
            <span class="n">dist</span> <span class="o">=</span> <span class="n">site</span><span class="o">.</span><span class="n">distance_from_point</span><span class="p">(</span><span class="n">pt</span><span class="p">)</span>
            <span class="k">if</span> <span class="n">dist</span> <span class="o">&lt;=</span> <span class="n">r</span><span class="p">:</span>
                <span class="n">neighbors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Neighbor</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span>
                                          <span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span> <span class="n">dist</span><span class="p">,</span> <span class="n">i</span><span class="p">))</span>
        <span class="k">return</span> <span class="n">neighbors</span></div>

<div class="viewcode-block" id="IMolecule.get_neighbors"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_neighbors">[docs]</a>    <span class="k">def</span> <span class="nf">get_neighbors</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">site</span><span class="p">,</span> <span class="n">r</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Get all neighbors to a site within a sphere of radius r.  Excludes the</span>
<span class="sd">        site itself.</span>

<span class="sd">        Args:</span>
<span class="sd">            site (Site): Site at the center of the sphere.</span>
<span class="sd">            r (float): Radius of sphere.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [(site, dist) ...] since most of the time, subsequent processing</span>
<span class="sd">            requires the distance.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">nns</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_sites_in_sphere</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span> <span class="n">r</span><span class="p">)</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">nn</span> <span class="k">for</span> <span class="n">nn</span> <span class="ow">in</span> <span class="n">nns</span> <span class="k">if</span> <span class="n">nn</span> <span class="o">!=</span> <span class="n">site</span><span class="p">]</span></div>

<div class="viewcode-block" id="IMolecule.get_neighbors_in_shell"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_neighbors_in_shell">[docs]</a>    <span class="k">def</span> <span class="nf">get_neighbors_in_shell</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">origin</span><span class="p">,</span> <span class="n">r</span><span class="p">,</span> <span class="n">dr</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns all sites in a shell centered on origin (coords) between radii</span>
<span class="sd">        r-dr and r+dr.</span>

<span class="sd">        Args:</span>
<span class="sd">            origin (3x1 array): Cartesian coordinates of center of sphere.</span>
<span class="sd">            r (float): Inner radius of shell.</span>
<span class="sd">            dr (float): Width of shell.</span>

<span class="sd">        Returns:</span>
<span class="sd">            [(site, dist) ...] since most of the time, subsequent processing</span>
<span class="sd">            requires the distance.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">outer</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_sites_in_sphere</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">r</span> <span class="o">+</span> <span class="n">dr</span><span class="p">)</span>
        <span class="n">inner</span> <span class="o">=</span> <span class="n">r</span> <span class="o">-</span> <span class="n">dr</span>
        <span class="k">return</span> <span class="p">[</span><span class="n">nn</span> <span class="k">for</span> <span class="n">nn</span> <span class="ow">in</span> <span class="n">outer</span> <span class="k">if</span> <span class="n">nn</span><span class="o">.</span><span class="n">nn_distance</span> <span class="o">&gt;</span> <span class="n">inner</span><span class="p">]</span></div>

<div class="viewcode-block" id="IMolecule.get_boxed_structure"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_boxed_structure">[docs]</a>    <span class="k">def</span> <span class="nf">get_boxed_structure</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">,</span> <span class="n">c</span><span class="p">,</span> <span class="n">images</span><span class="o">=</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span>
                            <span class="n">random_rotation</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">min_dist</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="bp">cls</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
                            <span class="n">offset</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">no_cross</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">reorder</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Creates a Structure from a Molecule by putting the Molecule in the</span>
<span class="sd">        center of a orthorhombic box. Useful for creating Structure for</span>
<span class="sd">        calculating molecules using periodic codes.</span>

<span class="sd">        Args:</span>
<span class="sd">            a (float): a-lattice parameter.</span>
<span class="sd">            b (float): b-lattice parameter.</span>
<span class="sd">            c (float): c-lattice parameter.</span>
<span class="sd">            images: No. of boxed images in each direction. Defaults to</span>
<span class="sd">                (1, 1, 1), meaning single molecule with 1 lattice parameter</span>
<span class="sd">                in each direction.</span>
<span class="sd">            random_rotation (bool): Whether to apply a random rotation to</span>
<span class="sd">                each molecule. This jumbles all the molecules so that they</span>
<span class="sd">                are not exact images of each other.</span>
<span class="sd">            min_dist (float): The minimum distance that atoms should be from</span>
<span class="sd">                each other. This is only used if random_rotation is True.</span>
<span class="sd">                The randomized rotations are searched such that no two atoms</span>
<span class="sd">                are less than min_dist from each other.</span>
<span class="sd">            cls: The Structure class to instantiate (defaults to pymatgen</span>
<span class="sd">                structure)</span>
<span class="sd">            offset: Translation to offset molecule from center of mass coords</span>
<span class="sd">            no_cross: Whether to forbid molecule coords from extending beyond</span>
<span class="sd">                boundary of box.</span>
<span class="sd">            reorder: Whether to reorder the sites to be in electronegativity</span>
<span class="sd">                order.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Structure containing molecule in a box.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">offset</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">offset</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])</span>

        <span class="n">coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">)</span>
        <span class="n">x_range</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">coords</span><span class="p">[:,</span> <span class="mi">0</span><span class="p">])</span> <span class="o">-</span> <span class="nb">min</span><span class="p">(</span><span class="n">coords</span><span class="p">[:,</span> <span class="mi">0</span><span class="p">])</span>
        <span class="n">y_range</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">coords</span><span class="p">[:,</span> <span class="mi">1</span><span class="p">])</span> <span class="o">-</span> <span class="nb">min</span><span class="p">(</span><span class="n">coords</span><span class="p">[:,</span> <span class="mi">1</span><span class="p">])</span>
        <span class="n">z_range</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">coords</span><span class="p">[:,</span> <span class="mi">2</span><span class="p">])</span> <span class="o">-</span> <span class="nb">min</span><span class="p">(</span><span class="n">coords</span><span class="p">[:,</span> <span class="mi">2</span><span class="p">])</span>

        <span class="k">if</span> <span class="n">a</span> <span class="o">&lt;=</span> <span class="n">x_range</span> <span class="ow">or</span> <span class="n">b</span> <span class="o">&lt;=</span> <span class="n">y_range</span> <span class="ow">or</span> <span class="n">c</span> <span class="o">&lt;=</span> <span class="n">z_range</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Box is not big enough to contain Molecule.&quot;</span><span class="p">)</span>
        <span class="n">lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="o">.</span><span class="n">from_parameters</span><span class="p">(</span><span class="n">a</span> <span class="o">*</span> <span class="n">images</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">b</span> <span class="o">*</span> <span class="n">images</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span>
                                          <span class="n">c</span> <span class="o">*</span> <span class="n">images</span><span class="p">[</span><span class="mi">2</span><span class="p">],</span>
                                          <span class="mi">90</span><span class="p">,</span> <span class="mi">90</span><span class="p">,</span> <span class="mi">90</span><span class="p">)</span>
        <span class="n">nimages</span> <span class="o">=</span> <span class="n">images</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">*</span> <span class="n">images</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">*</span> <span class="n">images</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>
        <span class="n">coords</span> <span class="o">=</span> <span class="p">[]</span>

        <span class="n">centered_coords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span> <span class="o">-</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_of_mass</span> <span class="o">+</span> <span class="n">offset</span>

        <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">itertools</span><span class="o">.</span><span class="n">product</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">images</span><span class="p">[</span><span class="mi">0</span><span class="p">])),</span>
                                         <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">images</span><span class="p">[</span><span class="mi">1</span><span class="p">])),</span>
                                         <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="n">images</span><span class="p">[</span><span class="mi">2</span><span class="p">]))):</span>
            <span class="n">box_center</span> <span class="o">=</span> <span class="p">[(</span><span class="n">i</span> <span class="o">+</span> <span class="mf">0.5</span><span class="p">)</span> <span class="o">*</span> <span class="n">a</span><span class="p">,</span> <span class="p">(</span><span class="n">j</span> <span class="o">+</span> <span class="mf">0.5</span><span class="p">)</span> <span class="o">*</span> <span class="n">b</span><span class="p">,</span> <span class="p">(</span><span class="n">k</span> <span class="o">+</span> <span class="mf">0.5</span><span class="p">)</span> <span class="o">*</span> <span class="n">c</span><span class="p">]</span>
            <span class="k">if</span> <span class="n">random_rotation</span><span class="p">:</span>
                <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
                    <span class="n">op</span> <span class="o">=</span> <span class="n">SymmOp</span><span class="o">.</span><span class="n">from_origin_axis_angle</span><span class="p">(</span>
                        <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">),</span> <span class="n">axis</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">rand</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span>
                        <span class="n">angle</span><span class="o">=</span><span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="o">-</span><span class="mi">180</span><span class="p">,</span> <span class="mi">180</span><span class="p">))</span>
                    <span class="n">m</span> <span class="o">=</span> <span class="n">op</span><span class="o">.</span><span class="n">rotation_matrix</span>
                    <span class="n">new_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">m</span><span class="p">,</span> <span class="n">centered_coords</span><span class="o">.</span><span class="n">T</span><span class="p">)</span><span class="o">.</span><span class="n">T</span> <span class="o">+</span> <span class="n">box_center</span>
                    <span class="k">if</span> <span class="n">no_cross</span><span class="p">:</span>
                        <span class="n">x_max</span><span class="p">,</span> <span class="n">x_min</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">0</span><span class="p">]),</span> <span class="nb">min</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">0</span><span class="p">])</span>
                        <span class="n">y_max</span><span class="p">,</span> <span class="n">y_min</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">1</span><span class="p">]),</span> <span class="nb">min</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">1</span><span class="p">])</span>
                        <span class="n">z_max</span><span class="p">,</span> <span class="n">z_min</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">2</span><span class="p">]),</span> <span class="nb">min</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">2</span><span class="p">])</span>
                        <span class="k">if</span> <span class="n">x_max</span> <span class="o">&gt;</span> <span class="n">a</span> <span class="ow">or</span> <span class="n">x_min</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="n">y_max</span> <span class="o">&gt;</span> <span class="n">b</span> <span class="ow">or</span> <span class="n">y_min</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="n">z_max</span> <span class="o">&gt;</span> <span class="n">c</span> <span class="ow">or</span> <span class="n">z_min</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>
                            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Molecule crosses boundary of box.&quot;</span><span class="p">)</span>
                    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
                        <span class="k">break</span>
                    <span class="n">distances</span> <span class="o">=</span> <span class="n">lattice</span><span class="o">.</span><span class="n">get_all_distances</span><span class="p">(</span>
                        <span class="n">lattice</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">new_coords</span><span class="p">),</span>
                        <span class="n">lattice</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">coords</span><span class="p">))</span>
                    <span class="k">if</span> <span class="n">np</span><span class="o">.</span><span class="n">amin</span><span class="p">(</span><span class="n">distances</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">min_dist</span><span class="p">:</span>
                        <span class="k">break</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="n">new_coords</span> <span class="o">=</span> <span class="n">centered_coords</span> <span class="o">+</span> <span class="n">box_center</span>
                <span class="k">if</span> <span class="n">no_cross</span><span class="p">:</span>
                    <span class="n">x_max</span><span class="p">,</span> <span class="n">x_min</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">0</span><span class="p">]),</span> <span class="nb">min</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">0</span><span class="p">])</span>
                    <span class="n">y_max</span><span class="p">,</span> <span class="n">y_min</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">1</span><span class="p">]),</span> <span class="nb">min</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">1</span><span class="p">])</span>
                    <span class="n">z_max</span><span class="p">,</span> <span class="n">z_min</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">2</span><span class="p">]),</span> <span class="nb">min</span><span class="p">(</span><span class="n">new_coords</span><span class="p">[:,</span> <span class="mi">2</span><span class="p">])</span>
                    <span class="k">if</span> <span class="n">x_max</span> <span class="o">&gt;</span> <span class="n">a</span> <span class="ow">or</span> <span class="n">x_min</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="n">y_max</span> <span class="o">&gt;</span> <span class="n">b</span> <span class="ow">or</span> <span class="n">y_min</span> <span class="o">&lt;</span> <span class="mi">0</span> <span class="ow">or</span> <span class="n">z_max</span> <span class="o">&gt;</span> <span class="n">c</span> <span class="ow">or</span> <span class="n">z_min</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>
                        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Molecule crosses boundary of box.&quot;</span><span class="p">)</span>
            <span class="n">coords</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">new_coords</span><span class="p">)</span>
        <span class="n">sprops</span> <span class="o">=</span> <span class="p">{</span><span class="n">k</span><span class="p">:</span> <span class="n">v</span> <span class="o">*</span> <span class="n">nimages</span> <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span><span class="o">.</span><span class="n">items</span><span class="p">()}</span>

        <span class="k">if</span> <span class="bp">cls</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="bp">cls</span> <span class="o">=</span> <span class="n">Structure</span>

        <span class="k">if</span> <span class="n">reorder</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">lattice</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">species</span> <span class="o">*</span> <span class="n">nimages</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span>
                       <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                       <span class="n">site_properties</span><span class="o">=</span><span class="n">sprops</span><span class="p">)</span><span class="o">.</span><span class="n">get_sorted_structure</span><span class="p">()</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">lattice</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">species</span> <span class="o">*</span> <span class="n">nimages</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span>
                       <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                       <span class="n">site_properties</span><span class="o">=</span><span class="n">sprops</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.get_centered_molecule"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.get_centered_molecule">[docs]</a>    <span class="k">def</span> <span class="nf">get_centered_molecule</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Returns a Molecule centered at the center of mass.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Molecule centered with center of mass at origin.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">center</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">center_of_mass</span>
        <span class="n">new_coords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">cart_coords</span><span class="p">)</span> <span class="o">-</span> <span class="n">center</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">species_and_occu</span><span class="p">,</span> <span class="n">new_coords</span><span class="p">,</span>
                              <span class="n">charge</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span>
                              <span class="n">spin_multiplicity</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span><span class="p">,</span>
                              <span class="n">site_properties</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">site_properties</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.to"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.to">[docs]</a>    <span class="k">def</span> <span class="nf">to</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Outputs the molecule to a file or string.</span>

<span class="sd">        Args:</span>
<span class="sd">            fmt (str): Format to output to. Defaults to JSON unless filename</span>
<span class="sd">                is provided. If fmt is specifies, it overrides whatever the</span>
<span class="sd">                filename is. Options include &quot;xyz&quot;, &quot;gjf&quot;, &quot;g03&quot;, &quot;json&quot;. If</span>
<span class="sd">                you have OpenBabel installed, any of the formats supported by</span>
<span class="sd">                OpenBabel. Non-case sensitive.</span>
<span class="sd">            filename (str): If provided, output will be written to a file. If</span>
<span class="sd">                fmt is not specified, the format is determined from the</span>
<span class="sd">                filename. Defaults is None, i.e. string output.</span>

<span class="sd">        Returns:</span>
<span class="sd">            (str) if filename is None. None otherwise.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.xyz</span> <span class="kn">import</span> <span class="n">XYZ</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.gaussian</span> <span class="kn">import</span> <span class="n">GaussianInput</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.babel</span> <span class="kn">import</span> <span class="n">BabelMolAdaptor</span>

        <span class="n">fmt</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span> <span class="k">if</span> <span class="n">fmt</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">fmt</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
        <span class="n">fname</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">filename</span> <span class="ow">or</span> <span class="s2">&quot;&quot;</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;xyz&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.xyz*&quot;</span><span class="p">):</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">XYZ</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
        <span class="k">elif</span> <span class="nb">any</span><span class="p">([</span><span class="n">fmt</span> <span class="o">==</span> <span class="n">r</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.</span><span class="si">{}</span><span class="s2">*&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">r</span><span class="p">))</span>
                  <span class="k">for</span> <span class="n">r</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;gjf&quot;</span><span class="p">,</span> <span class="s2">&quot;g03&quot;</span><span class="p">,</span> <span class="s2">&quot;g09&quot;</span><span class="p">,</span> <span class="s2">&quot;com&quot;</span><span class="p">,</span> <span class="s2">&quot;inp&quot;</span><span class="p">]]):</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">GaussianInput</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;json&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.json*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span>
                                                                   <span class="s2">&quot;*.mson*&quot;</span><span class="p">):</span>
            <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
                <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="s2">&quot;wt&quot;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf8&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">(),</span> <span class="n">f</span><span class="p">)</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="k">return</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">())</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;yaml&quot;</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.yaml*&quot;</span><span class="p">):</span>
            <span class="kn">import</span> <span class="nn">ruamel.yaml</span> <span class="k">as</span> <span class="nn">yaml</span>

            <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
                <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;wt&quot;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf8&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
                    <span class="k">return</span> <span class="n">yaml</span><span class="o">.</span><span class="n">safe_dump</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">(),</span> <span class="n">f</span><span class="p">)</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="k">return</span> <span class="n">yaml</span><span class="o">.</span><span class="n">safe_dump</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">as_dict</span><span class="p">())</span>

        <span class="k">else</span><span class="p">:</span>
            <span class="n">m</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;\.(pdb|mol|mdl|sdf|sd|ml2|sy2|mol2|cml|mrv)&quot;</span><span class="p">,</span>
                          <span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span>
            <span class="k">if</span> <span class="p">(</span><span class="ow">not</span> <span class="n">fmt</span><span class="p">)</span> <span class="ow">and</span> <span class="n">m</span><span class="p">:</span>
                <span class="n">fmt</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
            <span class="n">writer</span> <span class="o">=</span> <span class="n">BabelMolAdaptor</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">writer</span><span class="o">.</span><span class="n">write_file</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">file_format</span><span class="o">=</span><span class="n">fmt</span><span class="p">)</span>

        <span class="k">if</span> <span class="n">filename</span><span class="p">:</span>
            <span class="n">writer</span><span class="o">.</span><span class="n">write_file</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
        <span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="n">writer</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.from_str"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.from_str">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_str</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">input_string</span><span class="p">,</span> <span class="n">fmt</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reads the molecule from a string.</span>

<span class="sd">        Args:</span>
<span class="sd">            input_string (str): String to parse.</span>
<span class="sd">            fmt (str): Format to output to. Defaults to JSON unless filename</span>
<span class="sd">                is provided. If fmt is specifies, it overrides whatever the</span>
<span class="sd">                filename is. Options include &quot;xyz&quot;, &quot;gjf&quot;, &quot;g03&quot;, &quot;json&quot;. If</span>
<span class="sd">                you have OpenBabel installed, any of the formats supported by</span>
<span class="sd">                OpenBabel. Non-case sensitive.</span>

<span class="sd">        Returns:</span>
<span class="sd">            IMolecule or Molecule.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.xyz</span> <span class="kn">import</span> <span class="n">XYZ</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.gaussian</span> <span class="kn">import</span> <span class="n">GaussianInput</span>
        <span class="k">if</span> <span class="n">fmt</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;xyz&quot;</span><span class="p">:</span>
            <span class="n">m</span> <span class="o">=</span> <span class="n">XYZ</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span><span class="o">.</span><span class="n">molecule</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;gjf&quot;</span><span class="p">,</span> <span class="s2">&quot;g03&quot;</span><span class="p">,</span> <span class="s2">&quot;g09&quot;</span><span class="p">,</span> <span class="s2">&quot;com&quot;</span><span class="p">,</span> <span class="s2">&quot;inp&quot;</span><span class="p">]:</span>
            <span class="n">m</span> <span class="o">=</span> <span class="n">GaussianInput</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span><span class="o">.</span><span class="n">molecule</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;json&quot;</span><span class="p">:</span>
            <span class="n">d</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
        <span class="k">elif</span> <span class="n">fmt</span> <span class="o">==</span> <span class="s2">&quot;yaml&quot;</span><span class="p">:</span>
            <span class="kn">import</span> <span class="nn">ruamel.yaml</span> <span class="k">as</span> <span class="nn">yaml</span>
            <span class="n">d</span> <span class="o">=</span> <span class="n">yaml</span><span class="o">.</span><span class="n">safe_load</span><span class="p">(</span><span class="n">input_string</span><span class="p">)</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_dict</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="kn">from</span> <span class="nn">pymatgen.io.babel</span> <span class="kn">import</span> <span class="n">BabelMolAdaptor</span>
            <span class="n">m</span> <span class="o">=</span> <span class="n">BabelMolAdaptor</span><span class="o">.</span><span class="n">from_string</span><span class="p">(</span><span class="n">input_string</span><span class="p">,</span>
                                            <span class="n">file_format</span><span class="o">=</span><span class="n">fmt</span><span class="p">)</span><span class="o">.</span><span class="n">pymatgen_mol</span>
        <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="n">m</span><span class="p">)</span></div>

<div class="viewcode-block" id="IMolecule.from_file"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.IMolecule.from_file">[docs]</a>    <span class="nd">@classmethod</span>
    <span class="k">def</span> <span class="nf">from_file</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">filename</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Reads a molecule from a file. Supported formats include xyz,</span>
<span class="sd">        gaussian input (gjf|g03|g09|com|inp), Gaussian output (.out|and</span>
<span class="sd">        pymatgen&#39;s JSON serialized molecules. Using openbabel,</span>
<span class="sd">        many more extensions are supported but requires openbabel to be</span>
<span class="sd">        installed.</span>

<span class="sd">        Args:</span>
<span class="sd">            filename (str): The filename to read from.</span>

<span class="sd">        Returns:</span>
<span class="sd">            Molecule</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">filename</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.gaussian</span> <span class="kn">import</span> <span class="n">GaussianOutput</span>
        <span class="k">with</span> <span class="n">zopen</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
            <span class="n">contents</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
        <span class="n">fname</span> <span class="o">=</span> <span class="n">filename</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
        <span class="k">if</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.xyz*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;xyz&quot;</span><span class="p">)</span>
        <span class="k">if</span> <span class="nb">any</span><span class="p">([</span><span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.</span><span class="si">{}</span><span class="s2">*&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">r</span><span class="p">))</span>
                <span class="k">for</span> <span class="n">r</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;gjf&quot;</span><span class="p">,</span> <span class="s2">&quot;g03&quot;</span><span class="p">,</span> <span class="s2">&quot;g09&quot;</span><span class="p">,</span> <span class="s2">&quot;com&quot;</span><span class="p">,</span> <span class="s2">&quot;inp&quot;</span><span class="p">]]):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;g09&quot;</span><span class="p">)</span>
        <span class="k">if</span> <span class="nb">any</span><span class="p">([</span><span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="o">.</span><span class="n">lower</span><span class="p">(),</span> <span class="s2">&quot;*.</span><span class="si">{}</span><span class="s2">*&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">r</span><span class="p">))</span>
                <span class="k">for</span> <span class="n">r</span> <span class="ow">in</span> <span class="p">[</span><span class="s2">&quot;out&quot;</span><span class="p">,</span> <span class="s2">&quot;lis&quot;</span><span class="p">,</span> <span class="s2">&quot;log&quot;</span><span class="p">]]):</span>
            <span class="k">return</span> <span class="n">GaussianOutput</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span><span class="o">.</span><span class="n">final_structure</span>
        <span class="k">if</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.json*&quot;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.mson*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;json&quot;</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">fnmatch</span><span class="p">(</span><span class="n">fname</span><span class="p">,</span> <span class="s2">&quot;*.yaml*&quot;</span><span class="p">):</span>
            <span class="k">return</span> <span class="bp">cls</span><span class="o">.</span><span class="n">from_str</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="n">fmt</span><span class="o">=</span><span class="s2">&quot;yaml&quot;</span><span class="p">)</span>
        <span class="kn">from</span> <span class="nn">pymatgen.io.babel</span> <span class="kn">import</span> <span class="n">BabelMolAdaptor</span>
        <span class="n">m</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;\.(pdb|mol|mdl|sdf|sd|ml2|sy2|mol2|cml|mrv)&quot;</span><span class="p">,</span>
                      <span class="n">filename</span><span class="o">.</span><span class="n">lower</span><span class="p">())</span>
        <span class="k">if</span> <span class="n">m</span><span class="p">:</span>
            <span class="n">new</span> <span class="o">=</span> <span class="n">BabelMolAdaptor</span><span class="o">.</span><span class="n">from_file</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span>
                                            <span class="n">m</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span><span class="o">.</span><span class="n">pymatgen_mol</span>
            <span class="n">new</span><span class="o">.</span><span class="vm">__class__</span> <span class="o">=</span> <span class="bp">cls</span>
            <span class="k">return</span> <span class="n">new</span>
        <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Cannot determine file type.&quot;</span><span class="p">)</span></div></div>


<div class="viewcode-block" id="Structure"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure">[docs]</a><span class="k">class</span> <span class="nc">Structure</span><span class="p">(</span><span class="n">IStructure</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">MutableSequence</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Mutable version of structure.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="fm">__hash__</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># type: ignore</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
                 <span class="n">lattice</span><span class="p">:</span> <span class="n">Union</span><span class="p">[</span><span class="n">List</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span> <span class="n">Lattice</span><span class="p">],</span>
                 <span class="n">species</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">,</span> <span class="n">Composition</span><span class="p">]],</span>
                 <span class="n">coords</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">float</span><span class="p">]],</span>
                 <span class="n">charge</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="n">validate_proximity</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">to_unit_cell</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">coords_are_cartesian</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">site_properties</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Create a periodic structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            lattice: The lattice, either as a pymatgen.core.lattice.Lattice or</span>
<span class="sd">                simply as any 2D array. Each row should correspond to a lattice</span>
<span class="sd">                vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a</span>
<span class="sd">                lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].</span>
<span class="sd">            species: List of species on each site. Can take in flexible input,</span>
<span class="sd">                including:</span>

<span class="sd">                i.  A sequence of element / specie specified either as string</span>
<span class="sd">                    symbols, e.g. [&quot;Li&quot;, &quot;Fe2+&quot;, &quot;P&quot;, ...] or atomic numbers,</span>
<span class="sd">                    e.g., (3, 56, ...) or actual Element or Specie objects.</span>

<span class="sd">                ii. List of dict of elements/species and occupancies, e.g.,</span>
<span class="sd">                    [{&quot;Fe&quot; : 0.5, &quot;Mn&quot;:0.5}, ...]. This allows the setup of</span>
<span class="sd">                    disordered structures.</span>
<span class="sd">            coords (Nx3 array): list of fractional/cartesian coordinates of</span>
<span class="sd">                each species.</span>
<span class="sd">            charge (int): overall charge of the structure. Defaults to behavior</span>
<span class="sd">                in SiteCollection where total charge is the sum of the oxidation</span>
<span class="sd">                states.</span>
<span class="sd">            validate_proximity (bool): Whether to check if there are sites</span>
<span class="sd">                that are less than 0.01 Ang apart. Defaults to False.</span>
<span class="sd">            to_unit_cell (bool): Whether to map all sites into the unit cell,</span>
<span class="sd">                i.e., fractional coords between 0 and 1. Defaults to False.</span>
<span class="sd">            coords_are_cartesian (bool): Set to True if you are providing</span>
<span class="sd">                coordinates in cartesian coordinates. Defaults to False.</span>
<span class="sd">            site_properties (dict): Properties associated with the sites as a</span>
<span class="sd">                dict of sequences, e.g., {&quot;magmom&quot;:[5,5,5,5]}. The sequences</span>
<span class="sd">                have to be the same length as the atomic species and</span>
<span class="sd">                fractional_coords. Defaults to None for no properties.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
            <span class="n">lattice</span><span class="p">,</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">,</span>
            <span class="n">validate_proximity</span><span class="o">=</span><span class="n">validate_proximity</span><span class="p">,</span> <span class="n">to_unit_cell</span><span class="o">=</span><span class="n">to_unit_cell</span><span class="p">,</span>
            <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="n">coords_are_cartesian</span><span class="p">,</span>
            <span class="n">site_properties</span><span class="o">=</span><span class="n">site_properties</span><span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)</span>  <span class="c1"># type: ignore</span>

    <span class="k">def</span> <span class="fm">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Modify a site in the structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int, [int], slice, Specie-like): Indices to change. You can</span>
<span class="sd">                specify these as an int, a list of int, or a species-like</span>
<span class="sd">                string.</span>
<span class="sd">            site (PeriodicSite/Specie/Sequence): Three options exist. You</span>
<span class="sd">                can provide a PeriodicSite directly (lattice will be</span>
<span class="sd">                checked). Or more conveniently, you can provide a</span>
<span class="sd">                specie-like object or a tuple of up to length 3.</span>

<span class="sd">            Examples:</span>
<span class="sd">                s[0] = &quot;Fe&quot;</span>
<span class="sd">                s[0] = Element(&quot;Fe&quot;)</span>
<span class="sd">                both replaces the species only.</span>
<span class="sd">                s[0] = &quot;Fe&quot;, [0.5, 0.5, 0.5]</span>
<span class="sd">                Replaces site and *fractional* coordinates. Any properties</span>
<span class="sd">                are inherited from current site.</span>
<span class="sd">                s[0] = &quot;Fe&quot;, [0.5, 0.5, 0.5], {&quot;spin&quot;: 2}</span>
<span class="sd">                Replaces site and *fractional* coordinates and properties.</span>

<span class="sd">                s[(0, 2, 3)] = &quot;Fe&quot;</span>
<span class="sd">                Replaces sites 0, 2 and 3 with Fe.</span>

<span class="sd">                s[0::2] = &quot;Fe&quot;</span>
<span class="sd">                Replaces all even index sites with Fe.</span>

<span class="sd">                s[&quot;Mn&quot;] = &quot;Fe&quot;</span>
<span class="sd">                Replaces all Mn in the structure with Fe. This is</span>
<span class="sd">                a short form for the more complex replace_species.</span>

<span class="sd">                s[&quot;Mn&quot;] = &quot;Fe0.5Co0.5&quot;</span>
<span class="sd">                Replaces all Mn in the structure with Fe: 0.5, Co: 0.5, i.e.,</span>
<span class="sd">                creates a disordered structure!</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="nb">int</span><span class="p">):</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="p">[</span><span class="n">i</span><span class="p">]</span>
        <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">)):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">replace_species</span><span class="p">({</span><span class="n">i</span><span class="p">:</span> <span class="n">site</span><span class="p">})</span>
            <span class="k">return</span>
        <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="nb">slice</span><span class="p">):</span>
            <span class="n">to_mod</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="p">[</span><span class="n">ii</span> <span class="k">for</span> <span class="n">ii</span><span class="p">,</span> <span class="n">s</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)</span>
                       <span class="k">if</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">to_mod</span><span class="p">]</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>

        <span class="k">for</span> <span class="n">ii</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">:</span>
            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">PeriodicSite</span><span class="p">):</span>
                <span class="k">if</span> <span class="n">site</span><span class="o">.</span><span class="n">lattice</span> <span class="o">!=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">:</span>
                    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;PeriodicSite added must have same lattice &quot;</span>
                                     <span class="s2">&quot;as Structure!&quot;</span><span class="p">)</span>
                <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">indices</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">1</span><span class="p">:</span>
                    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Site assignments makes sense only for &quot;</span>
                                     <span class="s2">&quot;single int indices!&quot;</span><span class="p">)</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span> <span class="o">=</span> <span class="n">site</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="ow">or</span> <span class="p">(</span>
                        <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Sequence</span><span class="p">)):</span>
                    <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">site</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">site</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
                    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">site</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
                        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">frac_coords</span> <span class="o">=</span> <span class="n">site</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
                    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">site</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">2</span><span class="p">:</span>
                        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span> <span class="o">=</span> <span class="n">site</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>

    <span class="k">def</span> <span class="fm">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Deletes a site from the Structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="fm">__delitem__</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>

    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">lattice</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        :return: Lattice assciated with structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span>

    <span class="nd">@lattice</span><span class="o">.</span><span class="n">setter</span>
    <span class="k">def</span> <span class="nf">lattice</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">lattice</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">lattice</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">:</span>
            <span class="n">site</span><span class="o">.</span><span class="n">lattice</span> <span class="o">=</span> <span class="n">lattice</span>

<div class="viewcode-block" id="Structure.append"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.append">[docs]</a>    <span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
               <span class="n">validate_proximity</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Append a site to the structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            species: Species of inserted site</span>
<span class="sd">            coords (3x1 array): Coordinates of inserted site</span>
<span class="sd">            coords_are_cartesian (bool): Whether coordinates are cartesian.</span>
<span class="sd">                Defaults to False.</span>
<span class="sd">            validate_proximity (bool): Whether to check if inserted site is</span>
<span class="sd">                too close to an existing site. Defaults to False.</span>
<span class="sd">            properties (dict): Properties of the site.</span>

<span class="sd">        Returns:</span>
<span class="sd">            New structure with inserted site.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span>
                           <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="n">coords_are_cartesian</span><span class="p">,</span>
                           <span class="n">validate_proximity</span><span class="o">=</span><span class="n">validate_proximity</span><span class="p">,</span>
                           <span class="n">properties</span><span class="o">=</span><span class="n">properties</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.insert"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.insert">[docs]</a>    <span class="k">def</span> <span class="nf">insert</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
               <span class="n">validate_proximity</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Insert a site to the structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int): Index to insert site</span>
<span class="sd">            species (species-like): Species of inserted site</span>
<span class="sd">            coords (3x1 array): Coordinates of inserted site</span>
<span class="sd">            coords_are_cartesian (bool): Whether coordinates are cartesian.</span>
<span class="sd">                Defaults to False.</span>
<span class="sd">            validate_proximity (bool): Whether to check if inserted site is</span>
<span class="sd">                too close to an existing site. Defaults to False.</span>
<span class="sd">            properties (dict): Properties associated with the site.</span>

<span class="sd">        Returns:</span>
<span class="sd">            New structure with inserted site.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">coords_are_cartesian</span><span class="p">:</span>
            <span class="n">new_site</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                    <span class="n">properties</span><span class="o">=</span><span class="n">properties</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">frac_coords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>
            <span class="n">new_site</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">frac_coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                    <span class="n">properties</span><span class="o">=</span><span class="n">properties</span><span class="p">)</span>

        <span class="k">if</span> <span class="n">validate_proximity</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
                <span class="k">if</span> <span class="n">site</span><span class="o">.</span><span class="n">distance</span><span class="p">(</span><span class="n">new_site</span><span class="p">)</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">DISTANCE_TOLERANCE</span><span class="p">:</span>
                    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;New site is too close to an existing &quot;</span>
                                     <span class="s2">&quot;site!&quot;</span><span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">new_site</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.replace"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.replace">[docs]</a>    <span class="k">def</span> <span class="nf">replace</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
                <span class="n">properties</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Replace a single site. Takes either a species or a dict of species and</span>
<span class="sd">        occupations.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int): Index of the site in the _sites list.</span>
<span class="sd">            species (species-like): Species of replacement site</span>
<span class="sd">            coords (3x1 array): Coordinates of replacement site. If None,</span>
<span class="sd">                the current coordinates are assumed.</span>
<span class="sd">            coords_are_cartesian (bool): Whether coordinates are cartesian.</span>
<span class="sd">                Defaults to False.</span>
<span class="sd">            properties (dict): Properties associated with the site.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">coords</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">frac_coords</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">frac_coords</span>
        <span class="k">elif</span> <span class="n">coords_are_cartesian</span><span class="p">:</span>
            <span class="n">frac_coords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">coords</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">frac_coords</span> <span class="o">=</span> <span class="n">coords</span>

        <span class="n">new_site</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">frac_coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                <span class="n">properties</span><span class="o">=</span><span class="n">properties</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">new_site</span></div>

<div class="viewcode-block" id="Structure.substitute"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.substitute">[docs]</a>    <span class="k">def</span> <span class="nf">substitute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">index</span><span class="p">,</span> <span class="n">func_grp</span><span class="p">,</span> <span class="n">bond_order</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Substitute atom at index with a functional group.</span>

<span class="sd">        Args:</span>
<span class="sd">            index (int): Index of atom to substitute.</span>
<span class="sd">            func_grp: Substituent molecule. There are two options:</span>

<span class="sd">                1. Providing an actual Molecule as the input. The first atom</span>
<span class="sd">                   must be a DummySpecie X, indicating the position of</span>
<span class="sd">                   nearest neighbor. The second atom must be the next</span>
<span class="sd">                   nearest atom. For example, for a methyl group</span>
<span class="sd">                   substitution, func_grp should be X-CH3, where X is the</span>
<span class="sd">                   first site and C is the second site. What the code will</span>
<span class="sd">                   do is to remove the index site, and connect the nearest</span>
<span class="sd">                   neighbor to the C atom in CH3. The X-C bond indicates the</span>
<span class="sd">                   directionality to connect the atoms.</span>
<span class="sd">                2. A string name. The molecule will be obtained from the</span>
<span class="sd">                   relevant template in func_groups.json.</span>
<span class="sd">            bond_order (int): A specified bond order to calculate the bond</span>
<span class="sd">                length between the attached functional group and the nearest</span>
<span class="sd">                neighbor site. Defaults to 1.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="c1"># Find the nearest neighbor that is not a terminal atom.</span>
        <span class="n">all_non_terminal_nn</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">nn</span><span class="p">,</span> <span class="n">dist</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">_</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_neighbors</span><span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">],</span> <span class="mi">3</span><span class="p">):</span>
            <span class="c1"># Check that the nn has neighbors within a sensible distance but</span>
            <span class="c1"># is not the site being substituted.</span>
            <span class="k">for</span> <span class="n">inn</span><span class="p">,</span> <span class="n">dist2</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">_</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_neighbors</span><span class="p">(</span><span class="n">nn</span><span class="p">,</span> <span class="mi">3</span><span class="p">):</span>
                <span class="k">if</span> <span class="n">inn</span> <span class="o">!=</span> <span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span> <span class="ow">and</span> \
                        <span class="n">dist2</span> <span class="o">&lt;</span> <span class="mf">1.2</span> <span class="o">*</span> <span class="n">get_bond_length</span><span class="p">(</span><span class="n">nn</span><span class="o">.</span><span class="n">specie</span><span class="p">,</span> <span class="n">inn</span><span class="o">.</span><span class="n">specie</span><span class="p">):</span>
                    <span class="n">all_non_terminal_nn</span><span class="o">.</span><span class="n">append</span><span class="p">((</span><span class="n">nn</span><span class="p">,</span> <span class="n">dist</span><span class="p">))</span>
                    <span class="k">break</span>

        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">all_non_terminal_nn</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">&quot;Can&#39;t find a non-terminal neighbor to attach&quot;</span>
                               <span class="s2">&quot; functional group to.&quot;</span><span class="p">)</span>

        <span class="n">non_terminal_nn</span> <span class="o">=</span> <span class="nb">min</span><span class="p">(</span><span class="n">all_non_terminal_nn</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">d</span><span class="p">:</span> <span class="n">d</span><span class="p">[</span><span class="mi">1</span><span class="p">])[</span><span class="mi">0</span><span class="p">]</span>

        <span class="c1"># Set the origin point to be the coordinates of the nearest</span>
        <span class="c1"># non-terminal neighbor.</span>
        <span class="n">origin</span> <span class="o">=</span> <span class="n">non_terminal_nn</span><span class="o">.</span><span class="n">coords</span>

        <span class="c1"># Pass value of functional group--either from user-defined or from</span>
        <span class="c1"># functional.json</span>
        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">func_grp</span><span class="p">,</span> <span class="n">Molecule</span><span class="p">):</span>
            <span class="n">func_grp</span> <span class="o">=</span> <span class="n">func_grp</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="c1"># Check to see whether the functional group is in database.</span>
            <span class="k">if</span> <span class="n">func_grp</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">FunctionalGroups</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">&quot;Can&#39;t find functional group in list. &quot;</span>
                                   <span class="s2">&quot;Provide explicit coordinate instead&quot;</span><span class="p">)</span>
            <span class="n">func_grp</span> <span class="o">=</span> <span class="n">FunctionalGroups</span><span class="p">[</span><span class="n">func_grp</span><span class="p">]</span>

        <span class="c1"># If a bond length can be found, modify func_grp so that the X-group</span>
        <span class="c1"># bond length is equal to the bond length.</span>
        <span class="k">try</span><span class="p">:</span>
            <span class="n">bl</span> <span class="o">=</span> <span class="n">get_bond_length</span><span class="p">(</span><span class="n">non_terminal_nn</span><span class="o">.</span><span class="n">specie</span><span class="p">,</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">specie</span><span class="p">,</span>
                                 <span class="n">bond_order</span><span class="o">=</span><span class="n">bond_order</span><span class="p">)</span>
        <span class="c1"># Catches for case of incompatibility between Element(s) and Specie(s)</span>
        <span class="k">except</span> <span class="ne">TypeError</span><span class="p">:</span>
            <span class="n">bl</span> <span class="o">=</span> <span class="kc">None</span>

        <span class="k">if</span> <span class="n">bl</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">func_grp</span> <span class="o">=</span> <span class="n">func_grp</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
            <span class="n">vec</span> <span class="o">=</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
            <span class="n">vec</span> <span class="o">/=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">vec</span><span class="p">)</span>
            <span class="n">func_grp</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;X&quot;</span><span class="p">,</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">+</span> <span class="nb">float</span><span class="p">(</span><span class="n">bl</span><span class="p">)</span> <span class="o">*</span> <span class="n">vec</span>

        <span class="c1"># Align X to the origin.</span>
        <span class="n">x</span> <span class="o">=</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
        <span class="n">func_grp</span><span class="o">.</span><span class="n">translate_sites</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">func_grp</span><span class="p">))),</span> <span class="n">origin</span> <span class="o">-</span> <span class="n">x</span><span class="o">.</span><span class="n">coords</span><span class="p">)</span>

        <span class="c1"># Find angle between the attaching bond and the bond to be replaced.</span>
        <span class="n">v1</span> <span class="o">=</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">origin</span>
        <span class="n">v2</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">origin</span>
        <span class="n">angle</span> <span class="o">=</span> <span class="n">get_angle</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v2</span><span class="p">)</span>

        <span class="k">if</span> <span class="mi">1</span> <span class="o">&lt;</span> <span class="nb">abs</span><span class="p">(</span><span class="n">angle</span> <span class="o">%</span> <span class="mi">180</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">179</span><span class="p">:</span>
            <span class="c1"># For angles which are not 0 or 180, we perform a rotation about</span>
            <span class="c1"># the origin along an axis perpendicular to both bonds to align</span>
            <span class="c1"># bonds.</span>
            <span class="n">axis</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">cross</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v2</span><span class="p">)</span>
            <span class="n">op</span> <span class="o">=</span> <span class="n">SymmOp</span><span class="o">.</span><span class="n">from_origin_axis_angle</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">axis</span><span class="p">,</span> <span class="n">angle</span><span class="p">)</span>
            <span class="n">func_grp</span><span class="o">.</span><span class="n">apply_operation</span><span class="p">(</span><span class="n">op</span><span class="p">)</span>
        <span class="k">elif</span> <span class="nb">abs</span><span class="p">(</span><span class="nb">abs</span><span class="p">(</span><span class="n">angle</span><span class="p">)</span> <span class="o">-</span> <span class="mi">180</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>
            <span class="c1"># We have a 180 degree angle. Simply do an inversion about the</span>
            <span class="c1"># origin</span>
            <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">fg</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">func_grp</span><span class="p">):</span>
                <span class="n">func_grp</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">fg</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">origin</span> <span class="o">-</span> <span class="p">(</span><span class="n">fg</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">origin</span><span class="p">))</span>

        <span class="c1"># Remove the atom to be replaced, and add the rest of the functional</span>
        <span class="c1"># group.</span>
        <span class="k">del</span> <span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">:]:</span>
            <span class="n">s_new</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span>
                                 <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="p">,</span> <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">s_new</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.remove_species"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.remove_species">[docs]</a>    <span class="k">def</span> <span class="nf">remove_species</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">species</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Remove all occurrences of several species from a structure.</span>

<span class="sd">        Args:</span>
<span class="sd">            species: Sequence of species to remove, e.g., [&quot;Li&quot;, &quot;Na&quot;].</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">new_sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">species</span> <span class="o">=</span> <span class="p">[</span><span class="n">get_el_sp</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">species</span><span class="p">]</span>

        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">:</span>
            <span class="n">new_sp_occu</span> <span class="o">=</span> <span class="p">{</span><span class="n">sp</span><span class="p">:</span> <span class="n">amt</span> <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">amt</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
                           <span class="k">if</span> <span class="n">sp</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">species</span><span class="p">}</span>
            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">new_sp_occu</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
                <span class="n">new_sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">PeriodicSite</span><span class="p">(</span>
                    <span class="n">new_sp_occu</span><span class="p">,</span> <span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                    <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">))</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="n">new_sites</span></div>

<div class="viewcode-block" id="Structure.remove_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.remove_sites">[docs]</a>    <span class="k">def</span> <span class="nf">remove_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indices</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Delete sites with at indices.</span>

<span class="sd">        Args:</span>
<span class="sd">            indices: Sequence of indices of sites to delete.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="p">[</span><span class="n">s</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">s</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)</span>
                       <span class="k">if</span> <span class="n">i</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">]</span></div>

<div class="viewcode-block" id="Structure.apply_operation"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.apply_operation">[docs]</a>    <span class="k">def</span> <span class="nf">apply_operation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">symmop</span><span class="p">,</span> <span class="n">fractional</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Apply a symmetry operation to the structure and return the new</span>
<span class="sd">        structure. The lattice is operated by the rotation matrix only.</span>
<span class="sd">        Coords are operated in full and then transformed to the new lattice.</span>

<span class="sd">        Args:</span>
<span class="sd">            symmop (SymmOp): Symmetry operation to apply.</span>
<span class="sd">            fractional (bool): Whether the symmetry operation is applied in</span>
<span class="sd">                fractional space. Defaults to False, i.e., symmetry operation</span>
<span class="sd">                is applied in cartesian coordinates.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="n">fractional</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">([</span><span class="n">symmop</span><span class="o">.</span><span class="n">apply_rotation_only</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
                                     <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">matrix</span><span class="p">])</span>

            <span class="k">def</span> <span class="nf">operate_site</span><span class="p">(</span><span class="n">site</span><span class="p">):</span>
                <span class="n">new_cart</span> <span class="o">=</span> <span class="n">symmop</span><span class="o">.</span><span class="n">operate</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">)</span>
                <span class="n">new_frac</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span><span class="n">new_cart</span><span class="p">)</span>
                <span class="k">return</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">new_frac</span><span class="p">,</span>
                                    <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                    <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                                    <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

        <span class="k">else</span><span class="p">:</span>
            <span class="n">new_latt</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">symmop</span><span class="o">.</span><span class="n">rotation_matrix</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">matrix</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">new_latt</span><span class="p">)</span>

            <span class="k">def</span> <span class="nf">operate_site</span><span class="p">(</span><span class="n">site</span><span class="p">):</span>
                <span class="k">return</span> <span class="n">PeriodicSite</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span>
                                    <span class="n">symmop</span><span class="o">.</span><span class="n">operate</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span><span class="p">),</span>
                                    <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                                    <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                                    <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="p">[</span><span class="n">operate_site</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">]</span></div>

    <span class="nd">@deprecated</span><span class="p">(</span><span class="n">message</span><span class="o">=</span><span class="s2">&quot;Simply set using Structure.lattice = lattice. This will be removed in pymatgen v2020.&quot;</span><span class="p">)</span>
    <span class="k">def</span> <span class="nf">modify_lattice</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">new_lattice</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Modify the lattice of the structure.  Mainly used for changing the</span>
<span class="sd">        basis.</span>

<span class="sd">        Args:</span>
<span class="sd">            new_lattice (Lattice): New lattice</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">new_lattice</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">:</span>
            <span class="n">site</span><span class="o">.</span><span class="n">lattice</span> <span class="o">=</span> <span class="n">new_lattice</span>

<div class="viewcode-block" id="Structure.apply_strain"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.apply_strain">[docs]</a>    <span class="k">def</span> <span class="nf">apply_strain</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">strain</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Apply a strain to the lattice.</span>

<span class="sd">        Args:</span>
<span class="sd">            strain (float or list): Amount of strain to apply. Can be a float,</span>
<span class="sd">                or a sequence of 3 numbers. E.g., 0.01 means all lattice</span>
<span class="sd">                vectors are increased by 1%. This is equivalent to calling</span>
<span class="sd">                modify_lattice with a lattice with lattice parameters that</span>
<span class="sd">                are 1% larger.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">s</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">strain</span><span class="p">))</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">eye</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span> <span class="o">=</span> <span class="n">Lattice</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">matrix</span><span class="o">.</span><span class="n">T</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span><span class="o">.</span><span class="n">T</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.sort"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.sort">[docs]</a>    <span class="k">def</span> <span class="nf">sort</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Sort a structure in place. The parameters have the same meaning as in</span>
<span class="sd">        list.sort. By default, sites are sorted by the electronegativity of</span>
<span class="sd">        the species. The difference between this method and</span>
<span class="sd">        get_sorted_structure (which also works in IStructure) is that the</span>
<span class="sd">        latter returns a new Structure, while this just sorts the Structure</span>
<span class="sd">        in place.</span>

<span class="sd">        Args:</span>
<span class="sd">            key: Specifies a function of one argument that is used to extract</span>
<span class="sd">                a comparison key from each list element: key=str.lower. The</span>
<span class="sd">                default value is None (compare the elements directly).</span>
<span class="sd">            reverse (bool): If set to True, then the list elements are sorted</span>
<span class="sd">                as if each comparison were reversed.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="n">sort</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="n">key</span><span class="p">,</span> <span class="n">reverse</span><span class="o">=</span><span class="n">reverse</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.translate_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.translate_sites">[docs]</a>    <span class="k">def</span> <span class="nf">translate_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indices</span><span class="p">,</span> <span class="n">vector</span><span class="p">,</span> <span class="n">frac_coords</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                        <span class="n">to_unit_cell</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Translate specific sites by some vector, keeping the sites within the</span>
<span class="sd">        unit cell.</span>

<span class="sd">        Args:</span>
<span class="sd">            indices: Integer or List of site indices on which to perform the</span>
<span class="sd">                translation.</span>
<span class="sd">            vector: Translation vector for sites.</span>
<span class="sd">            frac_coords (bool): Whether the vector corresponds to fractional or</span>
<span class="sd">                cartesian coordinates.</span>
<span class="sd">            to_unit_cell (bool): Whether new sites are transformed to unit</span>
<span class="sd">                cell</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">indices</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Iterable</span><span class="p">):</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="p">[</span><span class="n">indices</span><span class="p">]</span>

        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">:</span>
            <span class="n">site</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
            <span class="k">if</span> <span class="n">frac_coords</span><span class="p">:</span>
                <span class="n">fcoords</span> <span class="o">=</span> <span class="n">site</span><span class="o">.</span><span class="n">frac_coords</span> <span class="o">+</span> <span class="n">vector</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="n">fcoords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">get_fractional_coords</span><span class="p">(</span>
                    <span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="o">+</span> <span class="n">vector</span><span class="p">)</span>
            <span class="k">if</span> <span class="n">to_unit_cell</span><span class="p">:</span>
                <span class="n">fcoords</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">mod</span><span class="p">(</span><span class="n">fcoords</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">frac_coords</span> <span class="o">=</span> <span class="n">fcoords</span></div>

<div class="viewcode-block" id="Structure.rotate_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.rotate_sites">[docs]</a>    <span class="k">def</span> <span class="nf">rotate_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indices</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">theta</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">anchor</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
                     <span class="n">to_unit_cell</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Rotate specific sites by some angle around vector at anchor.</span>

<span class="sd">        Args:</span>
<span class="sd">            indices (list): List of site indices on which to perform the</span>
<span class="sd">                translation.</span>
<span class="sd">            theta (float): Angle in radians</span>
<span class="sd">            axis (3x1 array): Rotation axis vector.</span>
<span class="sd">            anchor (3x1 array): Point of rotation.</span>
<span class="sd">            to_unit_cell (bool): Whether new sites are transformed to unit</span>
<span class="sd">                cell</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="kn">from</span> <span class="nn">numpy.linalg</span> <span class="kn">import</span> <span class="n">norm</span>
        <span class="kn">from</span> <span class="nn">numpy</span> <span class="kn">import</span> <span class="n">cross</span><span class="p">,</span> <span class="n">eye</span>
        <span class="kn">from</span> <span class="nn">scipy.linalg</span> <span class="kn">import</span> <span class="n">expm</span>

        <span class="k">if</span> <span class="n">indices</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>

        <span class="k">if</span> <span class="n">axis</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">axis</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span>

        <span class="k">if</span> <span class="n">anchor</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">anchor</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span>

        <span class="n">anchor</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span>
        <span class="n">axis</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">axis</span><span class="p">)</span>

        <span class="n">theta</span> <span class="o">%=</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">pi</span>

        <span class="n">rm</span> <span class="o">=</span> <span class="n">expm</span><span class="p">(</span><span class="n">cross</span><span class="p">(</span><span class="n">eye</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">axis</span> <span class="o">/</span> <span class="n">norm</span><span class="p">(</span><span class="n">axis</span><span class="p">))</span> <span class="o">*</span> <span class="n">theta</span><span class="p">)</span>
        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">:</span>
            <span class="n">site</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
            <span class="n">coords</span> <span class="o">=</span> <span class="p">((</span><span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">rm</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">T</span><span class="p">))</span><span class="o">.</span><span class="n">T</span> <span class="o">+</span> <span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">ravel</span><span class="p">()</span>
            <span class="n">new_site</span> <span class="o">=</span> <span class="n">PeriodicSite</span><span class="p">(</span>
                <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="p">,</span>
                <span class="n">to_unit_cell</span><span class="o">=</span><span class="n">to_unit_cell</span><span class="p">,</span> <span class="n">coords_are_cartesian</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
                <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">,</span>
                <span class="n">skip_checks</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">new_site</span></div>

<div class="viewcode-block" id="Structure.perturb"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.perturb">[docs]</a>    <span class="k">def</span> <span class="nf">perturb</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">distance</span><span class="p">,</span> <span class="n">min_distance</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Performs a random perturbation of the sites in a structure to break</span>
<span class="sd">        symmetries.</span>

<span class="sd">        Args:</span>
<span class="sd">            distance (float): Distance in angstroms by which to perturb each</span>
<span class="sd">                site.</span>
<span class="sd">            min_distance (None, int, or float): if None, all displacements will</span>
<span class="sd">                be equal amplitude. If int or float, perturb each site a</span>
<span class="sd">                distance drawn from the uniform distribution between</span>
<span class="sd">                &#39;min_distance&#39; and &#39;distance&#39;.</span>

<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">def</span> <span class="nf">get_rand_vec</span><span class="p">():</span>
            <span class="c1"># deals with zero vectors.</span>
            <span class="n">vector</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
            <span class="n">vnorm</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">vector</span><span class="p">)</span>
            <span class="n">dist</span> <span class="o">=</span> <span class="n">distance</span>
            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">min_distance</span><span class="p">,</span> <span class="p">(</span><span class="nb">float</span><span class="p">,</span> <span class="nb">int</span><span class="p">)):</span>
                <span class="n">dist</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="n">min_distance</span><span class="p">,</span> <span class="n">dist</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">vector</span> <span class="o">/</span> <span class="n">vnorm</span> <span class="o">*</span> <span class="n">dist</span> <span class="k">if</span> <span class="n">vnorm</span> <span class="o">!=</span> <span class="mi">0</span> <span class="k">else</span> <span class="n">get_rand_vec</span><span class="p">()</span>

        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">translate_sites</span><span class="p">([</span><span class="n">i</span><span class="p">],</span> <span class="n">get_rand_vec</span><span class="p">(),</span> <span class="n">frac_coords</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.make_supercell"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.make_supercell">[docs]</a>    <span class="k">def</span> <span class="nf">make_supercell</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">scaling_matrix</span><span class="p">,</span> <span class="n">to_unit_cell</span><span class="o">=</span><span class="kc">True</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Create a supercell.</span>

<span class="sd">        Args:</span>
<span class="sd">            scaling_matrix: A scaling matrix for transforming the lattice</span>
<span class="sd">                vectors. Has to be all integers. Several options are possible:</span>

<span class="sd">                a. A full 3x3 scaling matrix defining the linear combination</span>
<span class="sd">                   the old lattice vectors. E.g., [[2,1,0],[0,3,0],[0,0,</span>
<span class="sd">                   1]] generates a new structure with lattice vectors a&#39; =</span>
<span class="sd">                   2a + b, b&#39; = 3b, c&#39; = c where a, b, and c are the lattice</span>
<span class="sd">                   vectors of the original structure.</span>
<span class="sd">                b. An sequence of three scaling factors. E.g., [2, 1, 1]</span>
<span class="sd">                   specifies that the supercell should have dimensions 2a x b x</span>
<span class="sd">                   c.</span>
<span class="sd">                c. A number, which simply scales all lattice vectors by the</span>
<span class="sd">                   same factor.</span>
<span class="sd">            to_unit_cell: Whether or not to fall back sites into the unit cell</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">s</span> <span class="o">=</span> <span class="bp">self</span> <span class="o">*</span> <span class="n">scaling_matrix</span>
        <span class="k">if</span> <span class="n">to_unit_cell</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">s</span><span class="p">:</span>
                <span class="n">site</span><span class="o">.</span><span class="n">to_unit_cell</span><span class="p">(</span><span class="n">in_place</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">sites</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">lattice</span></div>

<div class="viewcode-block" id="Structure.scale_lattice"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.scale_lattice">[docs]</a>    <span class="k">def</span> <span class="nf">scale_lattice</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">volume</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Performs a scaling of the lattice vectors so that length proportions</span>
<span class="sd">        and angles are preserved.</span>

<span class="sd">        Args:</span>
<span class="sd">            volume (float): New volume of the unit cell in A^3.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_lattice</span><span class="o">.</span><span class="n">scale</span><span class="p">(</span><span class="n">volume</span><span class="p">)</span></div>

<div class="viewcode-block" id="Structure.merge_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.merge_sites">[docs]</a>    <span class="k">def</span> <span class="nf">merge_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tol</span><span class="o">=</span><span class="mf">0.01</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">&quot;sum&quot;</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Merges sites (adding occupancies) within tol of each other.</span>
<span class="sd">        Removes site properties.</span>

<span class="sd">        Args:</span>
<span class="sd">            tol (float): Tolerance for distance to merge sites.</span>
<span class="sd">            mode (str): Three modes supported. &quot;delete&quot; means duplicate sites are</span>
<span class="sd">                deleted. &quot;sum&quot; means the occupancies are summed for the sites.</span>
<span class="sd">                &quot;average&quot; means that the site is deleted but the properties are averaged</span>
<span class="sd">                Only first letter is considered.</span>

<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">mode</span> <span class="o">=</span> <span class="n">mode</span><span class="o">.</span><span class="n">lower</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span>
        <span class="kn">from</span> <span class="nn">scipy.spatial.distance</span> <span class="kn">import</span> <span class="n">squareform</span>
        <span class="kn">from</span> <span class="nn">scipy.cluster.hierarchy</span> <span class="kn">import</span> <span class="n">fcluster</span><span class="p">,</span> <span class="n">linkage</span>

        <span class="n">d</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">distance_matrix</span>
        <span class="n">np</span><span class="o">.</span><span class="n">fill_diagonal</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
        <span class="n">clusters</span> <span class="o">=</span> <span class="n">fcluster</span><span class="p">(</span><span class="n">linkage</span><span class="p">(</span><span class="n">squareform</span><span class="p">((</span><span class="n">d</span> <span class="o">+</span> <span class="n">d</span><span class="o">.</span><span class="n">T</span><span class="p">)</span> <span class="o">/</span> <span class="mi">2</span><span class="p">)),</span>
                            <span class="n">tol</span><span class="p">,</span> <span class="s1">&#39;distance&#39;</span><span class="p">)</span>
        <span class="n">sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">c</span> <span class="ow">in</span> <span class="n">np</span><span class="o">.</span><span class="n">unique</span><span class="p">(</span><span class="n">clusters</span><span class="p">):</span>
            <span class="n">inds</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">where</span><span class="p">(</span><span class="n">clusters</span> <span class="o">==</span> <span class="n">c</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
            <span class="n">species</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span><span class="o">.</span><span class="n">species</span>
            <span class="n">coords</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span><span class="o">.</span><span class="n">frac_coords</span>
            <span class="n">props</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">inds</span><span class="p">[</span><span class="mi">0</span><span class="p">]]</span><span class="o">.</span><span class="n">properties</span>
            <span class="k">for</span> <span class="n">n</span><span class="p">,</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">inds</span><span class="p">[</span><span class="mi">1</span><span class="p">:]):</span>
                <span class="n">sp</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">species</span>
                <span class="k">if</span> <span class="n">mode</span> <span class="o">==</span> <span class="s2">&quot;s&quot;</span><span class="p">:</span>
                    <span class="n">species</span> <span class="o">+=</span> <span class="n">sp</span>
                <span class="n">offset</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">frac_coords</span> <span class="o">-</span> <span class="n">coords</span>
                <span class="n">coords</span> <span class="o">=</span> <span class="n">coords</span> <span class="o">+</span> <span class="p">((</span><span class="n">offset</span> <span class="o">-</span> <span class="n">np</span><span class="o">.</span><span class="n">round</span><span class="p">(</span><span class="n">offset</span><span class="p">))</span> <span class="o">/</span> <span class="p">(</span><span class="n">n</span> <span class="o">+</span> <span class="mi">2</span><span class="p">))</span><span class="o">.</span><span class="n">astype</span><span class="p">(</span>
                    <span class="n">coords</span><span class="o">.</span><span class="n">dtype</span><span class="p">)</span>
                <span class="k">for</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">props</span><span class="o">.</span><span class="n">keys</span><span class="p">():</span>
                    <span class="k">if</span> <span class="n">props</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">!=</span> <span class="n">props</span><span class="p">[</span><span class="n">key</span><span class="p">]:</span>
                        <span class="k">if</span> <span class="n">mode</span> <span class="o">==</span> <span class="s1">&#39;a&#39;</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">props</span><span class="p">[</span><span class="n">key</span><span class="p">],</span> <span class="nb">float</span><span class="p">):</span>
                            <span class="c1"># update a running total</span>
                            <span class="n">props</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">props</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">*</span> <span class="p">(</span><span class="n">n</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span> <span class="o">/</span> <span class="p">(</span><span class="n">n</span> <span class="o">+</span> <span class="mi">2</span><span class="p">)</span> <span class="o">+</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">/</span> <span class="p">(</span><span class="n">n</span> <span class="o">+</span> <span class="mi">2</span><span class="p">)</span>
                        <span class="k">else</span><span class="p">:</span>
                            <span class="n">props</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
                            <span class="n">warnings</span><span class="o">.</span><span class="n">warn</span><span class="p">(</span><span class="s2">&quot;Sites with different site property </span><span class="si">%s</span><span class="s2"> are merged. &quot;</span>
                                          <span class="s2">&quot;So property is set to none&quot;</span> <span class="o">%</span> <span class="n">key</span><span class="p">)</span>
            <span class="n">sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">PeriodicSite</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">lattice</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="n">props</span><span class="p">))</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="n">sites</span></div>

<div class="viewcode-block" id="Structure.set_charge"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Structure.set_charge">[docs]</a>    <span class="k">def</span> <span class="nf">set_charge</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">new_charge</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Sets the overall structure charge</span>

<span class="sd">        Args:</span>
<span class="sd">            new_charge (float): new charge to set</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">=</span> <span class="n">new_charge</span></div></div>


<div class="viewcode-block" id="Molecule"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule">[docs]</a><span class="k">class</span> <span class="nc">Molecule</span><span class="p">(</span><span class="n">IMolecule</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">MutableSequence</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Mutable Molecule. It has all the methods in IMolecule, but in addition,</span>
<span class="sd">    it allows a user to perform edits on the molecule.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="fm">__hash__</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># type: ignore</span>

    <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span>
                 <span class="n">species</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Union</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">,</span> <span class="n">Composition</span><span class="p">]],</span>
                 <span class="n">coords</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="n">Sequence</span><span class="p">[</span><span class="nb">float</span><span class="p">]],</span>
                 <span class="n">charge</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span>
                 <span class="n">spin_multiplicity</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
                 <span class="n">validate_proximity</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
                 <span class="n">site_properties</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Creates a MutableMolecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            species: list of atomic species. Possible kinds of input include a</span>
<span class="sd">                list of dict of elements/species and occupancies, a List of</span>
<span class="sd">                elements/specie specified as actual Element/Specie, Strings</span>
<span class="sd">                (&quot;Fe&quot;, &quot;Fe2+&quot;) or atomic numbers (1,56).</span>
<span class="sd">            coords (3x1 array): list of cartesian coordinates of each species.</span>
<span class="sd">            charge (float): Charge for the molecule. Defaults to 0.</span>
<span class="sd">            spin_multiplicity (int): Spin multiplicity for molecule.</span>
<span class="sd">                Defaults to None, which means that the spin multiplicity is</span>
<span class="sd">                set to 1 if the molecule has no unpaired electrons and to 2</span>
<span class="sd">                if there are unpaired electrons.</span>
<span class="sd">            validate_proximity (bool): Whether to check if there are sites</span>
<span class="sd">                that are less than 1 Ang apart. Defaults to False.</span>
<span class="sd">            site_properties (dict): Properties associated with the sites as</span>
<span class="sd">                a dict of sequences, e.g., {&quot;magmom&quot;:[5,5,5,5]}. The</span>
<span class="sd">                sequences have to be the same length as the atomic species</span>
<span class="sd">                and fractional_coords. Defaults to None for no properties.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">charge</span><span class="o">=</span><span class="n">charge</span><span class="p">,</span>
                         <span class="n">spin_multiplicity</span><span class="o">=</span><span class="n">spin_multiplicity</span><span class="p">,</span>
                         <span class="n">validate_proximity</span><span class="o">=</span><span class="n">validate_proximity</span><span class="p">,</span>
                         <span class="n">site_properties</span><span class="o">=</span><span class="n">site_properties</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)</span>  <span class="c1"># type: ignore</span>

    <span class="k">def</span> <span class="fm">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">site</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Modify a site in the molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int, [int], slice, Specie-like): Indices to change. You can</span>
<span class="sd">                specify these as an int, a list of int, or a species-like</span>
<span class="sd">                string.</span>
<span class="sd">            site (PeriodicSite/Specie/Sequence): Three options exist. You can</span>
<span class="sd">                provide a Site directly, or for convenience, you can provide</span>
<span class="sd">                simply a Specie-like string/object, or finally a (Specie,</span>
<span class="sd">                coords) sequence, e.g., (&quot;Fe&quot;, [0.5, 0.5, 0.5]).</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="nb">int</span><span class="p">):</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="p">[</span><span class="n">i</span><span class="p">]</span>
        <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="n">Element</span><span class="p">,</span> <span class="n">Specie</span><span class="p">)):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">replace_species</span><span class="p">({</span><span class="n">i</span><span class="p">:</span> <span class="n">site</span><span class="p">})</span>
            <span class="k">return</span>
        <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="nb">slice</span><span class="p">):</span>
            <span class="n">to_mod</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="p">[</span><span class="n">ii</span> <span class="k">for</span> <span class="n">ii</span><span class="p">,</span> <span class="n">s</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)</span>
                       <span class="k">if</span> <span class="n">s</span> <span class="ow">in</span> <span class="n">to_mod</span><span class="p">]</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>

        <span class="k">for</span> <span class="n">ii</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">:</span>
            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">Site</span><span class="p">):</span>
                <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span> <span class="o">=</span> <span class="n">site</span>
            <span class="k">else</span><span class="p">:</span>
                <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="ow">or</span> <span class="p">(</span>
                        <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">site</span><span class="p">,</span> <span class="n">collections</span><span class="o">.</span><span class="n">abc</span><span class="o">.</span><span class="n">Sequence</span><span class="p">)):</span>
                    <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">site</span>
                <span class="k">else</span><span class="p">:</span>
                    <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">species</span> <span class="o">=</span> <span class="n">site</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
                    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">site</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
                        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">=</span> <span class="n">site</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
                    <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">site</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">2</span><span class="p">:</span>
                        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">ii</span><span class="p">]</span><span class="o">.</span><span class="n">properties</span> <span class="o">=</span> <span class="n">site</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span>

    <span class="k">def</span> <span class="fm">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Deletes a site from the Structure.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="fm">__delitem__</span><span class="p">(</span><span class="n">i</span><span class="p">)</span>

<div class="viewcode-block" id="Molecule.append"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.append">[docs]</a>    <span class="k">def</span> <span class="nf">append</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">validate_proximity</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Appends a site to the molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            species: Species of inserted site</span>
<span class="sd">            coords: Coordinates of inserted site</span>
<span class="sd">            validate_proximity (bool): Whether to check if inserted site is</span>
<span class="sd">                too close to an existing site. Defaults to True.</span>
<span class="sd">            properties (dict): A dict of properties for the Site.</span>

<span class="sd">        Returns:</span>
<span class="sd">            New molecule with inserted site.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span>
                           <span class="n">validate_proximity</span><span class="o">=</span><span class="n">validate_proximity</span><span class="p">,</span>
                           <span class="n">properties</span><span class="o">=</span><span class="n">properties</span><span class="p">)</span></div>

<div class="viewcode-block" id="Molecule.set_charge_and_spin"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.set_charge_and_spin">[docs]</a>    <span class="k">def</span> <span class="nf">set_charge_and_spin</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">charge</span><span class="p">:</span> <span class="nb">float</span><span class="p">,</span> <span class="n">spin_multiplicity</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">float</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Set the charge and spin multiplicity.</span>

<span class="sd">        Args:</span>
<span class="sd">            charge (int): Charge for the molecule. Defaults to 0.</span>
<span class="sd">            spin_multiplicity (int): Spin multiplicity for molecule.</span>
<span class="sd">                Defaults to None, which means that the spin multiplicity is</span>
<span class="sd">                set to 1 if the molecule has no unpaired electrons and to 2</span>
<span class="sd">                if there are unpaired electrons.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span> <span class="o">=</span> <span class="n">charge</span>
        <span class="n">nelectrons</span> <span class="o">=</span> <span class="mf">0.0</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">amt</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
                <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">sp</span><span class="p">,</span> <span class="n">DummySpecie</span><span class="p">):</span>
                    <span class="n">nelectrons</span> <span class="o">+=</span> <span class="n">sp</span><span class="o">.</span><span class="n">Z</span> <span class="o">*</span> <span class="n">amt</span>
        <span class="n">nelectrons</span> <span class="o">-=</span> <span class="n">charge</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_nelectrons</span> <span class="o">=</span> <span class="n">nelectrons</span>
        <span class="k">if</span> <span class="n">spin_multiplicity</span><span class="p">:</span>
            <span class="k">if</span> <span class="p">(</span><span class="n">nelectrons</span> <span class="o">+</span> <span class="n">spin_multiplicity</span><span class="p">)</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">!=</span> <span class="mi">1</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
                    <span class="s2">&quot;Charge of </span><span class="si">{}</span><span class="s2"> and spin multiplicity of </span><span class="si">{}</span><span class="s2"> is&quot;</span>
                    <span class="s2">&quot; not possible for this molecule&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
                        <span class="bp">self</span><span class="o">.</span><span class="n">_charge</span><span class="p">,</span> <span class="n">spin_multiplicity</span><span class="p">))</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span> <span class="o">=</span> <span class="n">spin_multiplicity</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_spin_multiplicity</span> <span class="o">=</span> <span class="mi">1</span> <span class="k">if</span> <span class="n">nelectrons</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="k">else</span> <span class="mi">2</span></div>

<div class="viewcode-block" id="Molecule.insert"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.insert">[docs]</a>    <span class="k">def</span> <span class="nf">insert</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">i</span><span class="p">,</span> <span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">validate_proximity</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
               <span class="n">properties</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Insert a site to the molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            i (int): Index to insert site</span>
<span class="sd">            species: species of inserted site</span>
<span class="sd">            coords (3x1 array): coordinates of inserted site</span>
<span class="sd">            validate_proximity (bool): Whether to check if inserted site is</span>
<span class="sd">                too close to an existing site. Defaults to True.</span>
<span class="sd">            properties (dict): Dict of properties for the Site.</span>

<span class="sd">        Returns:</span>
<span class="sd">            New molecule with inserted site.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">new_site</span> <span class="o">=</span> <span class="n">Site</span><span class="p">(</span><span class="n">species</span><span class="p">,</span> <span class="n">coords</span><span class="p">,</span> <span class="n">properties</span><span class="o">=</span><span class="n">properties</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">validate_proximity</span><span class="p">:</span>
            <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="p">:</span>
                <span class="k">if</span> <span class="n">site</span><span class="o">.</span><span class="n">distance</span><span class="p">(</span><span class="n">new_site</span><span class="p">)</span> <span class="o">&lt;</span> <span class="bp">self</span><span class="o">.</span><span class="n">DISTANCE_TOLERANCE</span><span class="p">:</span>
                    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;New site is too close to an existing &quot;</span>
                                     <span class="s2">&quot;site!&quot;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="n">insert</span><span class="p">(</span><span class="n">i</span><span class="p">,</span> <span class="n">new_site</span><span class="p">)</span></div>

<div class="viewcode-block" id="Molecule.remove_species"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.remove_species">[docs]</a>    <span class="k">def</span> <span class="nf">remove_species</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">species</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Remove all occurrences of a species from a molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            species: Species to remove.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="n">new_sites</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="n">species</span> <span class="o">=</span> <span class="p">[</span><span class="n">get_el_sp</span><span class="p">(</span><span class="n">sp</span><span class="p">)</span> <span class="k">for</span> <span class="n">sp</span> <span class="ow">in</span> <span class="n">species</span><span class="p">]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">:</span>
            <span class="n">new_sp_occu</span> <span class="o">=</span> <span class="p">{</span><span class="n">sp</span><span class="p">:</span> <span class="n">amt</span> <span class="k">for</span> <span class="n">sp</span><span class="p">,</span> <span class="n">amt</span> <span class="ow">in</span> <span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="o">.</span><span class="n">items</span><span class="p">()</span>
                           <span class="k">if</span> <span class="n">sp</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">species</span><span class="p">}</span>
            <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">new_sp_occu</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
                <span class="n">new_sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">Site</span><span class="p">(</span><span class="n">new_sp_occu</span><span class="p">,</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">,</span>
                                      <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">))</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="n">new_sites</span></div>

<div class="viewcode-block" id="Molecule.remove_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.remove_sites">[docs]</a>    <span class="k">def</span> <span class="nf">remove_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indices</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Delete sites with at indices.</span>

<span class="sd">        Args:</span>
<span class="sd">            indices: Sequence of indices of sites to delete.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">))</span>
                       <span class="k">if</span> <span class="n">i</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">]</span></div>

<div class="viewcode-block" id="Molecule.translate_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.translate_sites">[docs]</a>    <span class="k">def</span> <span class="nf">translate_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indices</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">vector</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Translate specific sites by some vector, keeping the sites within the</span>
<span class="sd">        unit cell.</span>

<span class="sd">        Args:</span>
<span class="sd">            indices (list): List of site indices on which to perform the</span>
<span class="sd">                translation.</span>
<span class="sd">            vector (3x1 array): Translation vector for sites.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">if</span> <span class="n">indices</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>
        <span class="k">if</span> <span class="n">vector</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">vector</span> <span class="o">==</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span>
        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">:</span>
            <span class="n">site</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
            <span class="n">new_site</span> <span class="o">=</span> <span class="n">Site</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="o">+</span> <span class="n">vector</span><span class="p">,</span>
                            <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">new_site</span></div>

<div class="viewcode-block" id="Molecule.rotate_sites"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.rotate_sites">[docs]</a>    <span class="k">def</span> <span class="nf">rotate_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">indices</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">theta</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">anchor</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Rotate specific sites by some angle around vector at anchor.</span>

<span class="sd">        Args:</span>
<span class="sd">            indices (list): List of site indices on which to perform the</span>
<span class="sd">                translation.</span>
<span class="sd">            theta (float): Angle in radians</span>
<span class="sd">            axis (3x1 array): Rotation axis vector.</span>
<span class="sd">            anchor (3x1 array): Point of rotation.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="kn">from</span> <span class="nn">numpy.linalg</span> <span class="kn">import</span> <span class="n">norm</span>
        <span class="kn">from</span> <span class="nn">numpy</span> <span class="kn">import</span> <span class="n">cross</span><span class="p">,</span> <span class="n">eye</span>
        <span class="kn">from</span> <span class="nn">scipy.linalg</span> <span class="kn">import</span> <span class="n">expm</span>

        <span class="k">if</span> <span class="n">indices</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">indices</span> <span class="o">=</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="p">))</span>

        <span class="k">if</span> <span class="n">axis</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">axis</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span>

        <span class="k">if</span> <span class="n">anchor</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">anchor</span> <span class="o">=</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]</span>

        <span class="n">anchor</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">anchor</span><span class="p">)</span>
        <span class="n">axis</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">(</span><span class="n">axis</span><span class="p">)</span>

        <span class="n">theta</span> <span class="o">%=</span> <span class="mi">2</span> <span class="o">*</span> <span class="n">np</span><span class="o">.</span><span class="n">pi</span>

        <span class="n">rm</span> <span class="o">=</span> <span class="n">expm</span><span class="p">(</span><span class="n">cross</span><span class="p">(</span><span class="n">eye</span><span class="p">(</span><span class="mi">3</span><span class="p">),</span> <span class="n">axis</span> <span class="o">/</span> <span class="n">norm</span><span class="p">(</span><span class="n">axis</span><span class="p">))</span> <span class="o">*</span> <span class="n">theta</span><span class="p">)</span>

        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">indices</span><span class="p">:</span>
            <span class="n">site</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span>
            <span class="n">s</span> <span class="o">=</span> <span class="p">((</span><span class="n">np</span><span class="o">.</span><span class="n">dot</span><span class="p">(</span><span class="n">rm</span><span class="p">,</span> <span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">T</span><span class="p">))</span><span class="o">.</span><span class="n">T</span> <span class="o">+</span> <span class="n">anchor</span><span class="p">)</span><span class="o">.</span><span class="n">ravel</span><span class="p">()</span>
            <span class="n">new_site</span> <span class="o">=</span> <span class="n">Site</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">s</span><span class="p">,</span>
                            <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">)</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">new_site</span></div>

<div class="viewcode-block" id="Molecule.perturb"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.perturb">[docs]</a>    <span class="k">def</span> <span class="nf">perturb</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">distance</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Performs a random perturbation of the sites in a structure to break</span>
<span class="sd">        symmetries.</span>

<span class="sd">        Args:</span>
<span class="sd">            distance (float): Distance in angstroms by which to perturb each</span>
<span class="sd">                site.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">def</span> <span class="nf">get_rand_vec</span><span class="p">():</span>
            <span class="c1"># deals with zero vectors.</span>
            <span class="n">vector</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">randn</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
            <span class="n">vnorm</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">vector</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">vector</span> <span class="o">/</span> <span class="n">vnorm</span> <span class="o">*</span> <span class="n">distance</span> <span class="k">if</span> <span class="n">vnorm</span> <span class="o">!=</span> <span class="mi">0</span> <span class="k">else</span> <span class="n">get_rand_vec</span><span class="p">()</span>

        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">)):</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">translate_sites</span><span class="p">([</span><span class="n">i</span><span class="p">],</span> <span class="n">get_rand_vec</span><span class="p">())</span></div>

<div class="viewcode-block" id="Molecule.apply_operation"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.apply_operation">[docs]</a>    <span class="k">def</span> <span class="nf">apply_operation</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">symmop</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Apply a symmetry operation to the molecule.</span>

<span class="sd">        Args:</span>
<span class="sd">            symmop (SymmOp): Symmetry operation to apply.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="k">def</span> <span class="nf">operate_site</span><span class="p">(</span><span class="n">site</span><span class="p">):</span>
            <span class="n">new_cart</span> <span class="o">=</span> <span class="n">symmop</span><span class="o">.</span><span class="n">operate</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">coords</span><span class="p">)</span>
            <span class="k">return</span> <span class="n">Site</span><span class="p">(</span><span class="n">site</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">new_cart</span><span class="p">,</span>
                        <span class="n">properties</span><span class="o">=</span><span class="n">site</span><span class="o">.</span><span class="n">properties</span><span class="p">)</span>

        <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span> <span class="o">=</span> <span class="p">[</span><span class="n">operate_site</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="k">for</span> <span class="n">s</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="p">]</span></div>

<div class="viewcode-block" id="Molecule.copy"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.copy">[docs]</a>    <span class="k">def</span> <span class="nf">copy</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Convenience method to get a copy of the molecule.</span>

<span class="sd">        Returns:</span>
<span class="sd">            A copy of the Molecule.</span>
<span class="sd">        &quot;&quot;&quot;</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="vm">__class__</span><span class="o">.</span><span class="n">from_sites</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span></div>

<div class="viewcode-block" id="Molecule.substitute"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.Molecule.substitute">[docs]</a>    <span class="k">def</span> <span class="nf">substitute</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">index</span><span class="p">,</span> <span class="n">func_grp</span><span class="p">,</span> <span class="n">bond_order</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">        Substitute atom at index with a functional group.</span>

<span class="sd">        Args:</span>
<span class="sd">            index (int): Index of atom to substitute.</span>
<span class="sd">            func_grp: Substituent molecule. There are two options:</span>

<span class="sd">                1. Providing an actual molecule as the input. The first atom</span>
<span class="sd">                   must be a DummySpecie X, indicating the position of</span>
<span class="sd">                   nearest neighbor. The second atom must be the next</span>
<span class="sd">                   nearest atom. For example, for a methyl group</span>
<span class="sd">                   substitution, func_grp should be X-CH3, where X is the</span>
<span class="sd">                   first site and C is the second site. What the code will</span>
<span class="sd">                   do is to remove the index site, and connect the nearest</span>
<span class="sd">                   neighbor to the C atom in CH3. The X-C bond indicates the</span>
<span class="sd">                   directionality to connect the atoms.</span>
<span class="sd">                2. A string name. The molecule will be obtained from the</span>
<span class="sd">                   relevant template in func_groups.json.</span>
<span class="sd">            bond_order (int): A specified bond order to calculate the bond</span>
<span class="sd">                length between the attached functional group and the nearest</span>
<span class="sd">                neighbor site. Defaults to 1.</span>
<span class="sd">        &quot;&quot;&quot;</span>

        <span class="c1"># Find the nearest neighbor that is not a terminal atom.</span>
        <span class="n">all_non_terminal_nn</span> <span class="o">=</span> <span class="p">[]</span>
        <span class="k">for</span> <span class="n">nn</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_neighbors</span><span class="p">(</span><span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">],</span> <span class="mi">3</span><span class="p">):</span>
            <span class="c1"># Check that the nn has neighbors within a sensible distance but</span>
            <span class="c1"># is not the site being substituted.</span>
            <span class="k">for</span> <span class="n">nn2</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_neighbors</span><span class="p">(</span><span class="n">nn</span><span class="p">,</span> <span class="mi">3</span><span class="p">):</span>
                <span class="k">if</span> <span class="n">nn2</span> <span class="o">!=</span> <span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span> <span class="ow">and</span> <span class="n">nn2</span><span class="o">.</span><span class="n">nn_distance</span> <span class="o">&lt;</span> <span class="mf">1.2</span> <span class="o">*</span> <span class="n">get_bond_length</span><span class="p">(</span><span class="n">nn</span><span class="o">.</span><span class="n">specie</span><span class="p">,</span> <span class="n">nn2</span><span class="o">.</span><span class="n">specie</span><span class="p">):</span>
                    <span class="n">all_non_terminal_nn</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">nn</span><span class="p">)</span>
                    <span class="k">break</span>

        <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">all_non_terminal_nn</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
            <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">&quot;Can&#39;t find a non-terminal neighbor to attach&quot;</span>
                               <span class="s2">&quot; functional group to.&quot;</span><span class="p">)</span>

        <span class="n">non_terminal_nn</span> <span class="o">=</span> <span class="nb">min</span><span class="p">(</span><span class="n">all_non_terminal_nn</span><span class="p">,</span> <span class="n">key</span><span class="o">=</span><span class="k">lambda</span> <span class="n">nn</span><span class="p">:</span> <span class="n">nn</span><span class="o">.</span><span class="n">nn_distance</span><span class="p">)</span>

        <span class="c1"># Set the origin point to be the coordinates of the nearest</span>
        <span class="c1"># non-terminal neighbor.</span>
        <span class="n">origin</span> <span class="o">=</span> <span class="n">non_terminal_nn</span><span class="o">.</span><span class="n">coords</span>

        <span class="c1"># Pass value of functional group--either from user-defined or from</span>
        <span class="c1"># functional.json</span>
        <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">func_grp</span><span class="p">,</span> <span class="n">Molecule</span><span class="p">):</span>
            <span class="n">func_grp</span> <span class="o">=</span> <span class="n">func_grp</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="c1"># Check to see whether the functional group is in database.</span>
            <span class="k">if</span> <span class="n">func_grp</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">FunctionalGroups</span><span class="p">:</span>
                <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s2">&quot;Can&#39;t find functional group in list. &quot;</span>
                                   <span class="s2">&quot;Provide explicit coordinate instead&quot;</span><span class="p">)</span>
            <span class="n">func_grp</span> <span class="o">=</span> <span class="n">FunctionalGroups</span><span class="p">[</span><span class="n">func_grp</span><span class="p">]</span>

        <span class="c1"># If a bond length can be found, modify func_grp so that the X-group</span>
        <span class="c1"># bond length is equal to the bond length.</span>
        <span class="n">bl</span> <span class="o">=</span> <span class="n">get_bond_length</span><span class="p">(</span><span class="n">non_terminal_nn</span><span class="o">.</span><span class="n">specie</span><span class="p">,</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">specie</span><span class="p">,</span>
                             <span class="n">bond_order</span><span class="o">=</span><span class="n">bond_order</span><span class="p">)</span>
        <span class="k">if</span> <span class="n">bl</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
            <span class="n">func_grp</span> <span class="o">=</span> <span class="n">func_grp</span><span class="o">.</span><span class="n">copy</span><span class="p">()</span>
            <span class="n">vec</span> <span class="o">=</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span>
            <span class="n">vec</span> <span class="o">/=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">norm</span><span class="p">(</span><span class="n">vec</span><span class="p">)</span>
            <span class="n">func_grp</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="s2">&quot;X&quot;</span><span class="p">,</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">+</span> <span class="nb">float</span><span class="p">(</span><span class="n">bl</span><span class="p">)</span> <span class="o">*</span> <span class="n">vec</span>

        <span class="c1"># Align X to the origin.</span>
        <span class="n">x</span> <span class="o">=</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
        <span class="n">func_grp</span><span class="o">.</span><span class="n">translate_sites</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">func_grp</span><span class="p">))),</span> <span class="n">origin</span> <span class="o">-</span> <span class="n">x</span><span class="o">.</span><span class="n">coords</span><span class="p">)</span>

        <span class="c1"># Find angle between the attaching bond and the bond to be replaced.</span>
        <span class="n">v1</span> <span class="o">=</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">origin</span>
        <span class="n">v2</span> <span class="o">=</span> <span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">origin</span>
        <span class="n">angle</span> <span class="o">=</span> <span class="n">get_angle</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v2</span><span class="p">)</span>

        <span class="k">if</span> <span class="mi">1</span> <span class="o">&lt;</span> <span class="nb">abs</span><span class="p">(</span><span class="n">angle</span> <span class="o">%</span> <span class="mi">180</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">179</span><span class="p">:</span>
            <span class="c1"># For angles which are not 0 or 180, we perform a rotation about</span>
            <span class="c1"># the origin along an axis perpendicular to both bonds to align</span>
            <span class="c1"># bonds.</span>
            <span class="n">axis</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">cross</span><span class="p">(</span><span class="n">v1</span><span class="p">,</span> <span class="n">v2</span><span class="p">)</span>
            <span class="n">op</span> <span class="o">=</span> <span class="n">SymmOp</span><span class="o">.</span><span class="n">from_origin_axis_angle</span><span class="p">(</span><span class="n">origin</span><span class="p">,</span> <span class="n">axis</span><span class="p">,</span> <span class="n">angle</span><span class="p">)</span>
            <span class="n">func_grp</span><span class="o">.</span><span class="n">apply_operation</span><span class="p">(</span><span class="n">op</span><span class="p">)</span>
        <span class="k">elif</span> <span class="nb">abs</span><span class="p">(</span><span class="nb">abs</span><span class="p">(</span><span class="n">angle</span><span class="p">)</span> <span class="o">-</span> <span class="mi">180</span><span class="p">)</span> <span class="o">&lt;</span> <span class="mi">1</span><span class="p">:</span>
            <span class="c1"># We have a 180 degree angle. Simply do an inversion about the</span>
            <span class="c1"># origin</span>
            <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">fg</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">func_grp</span><span class="p">):</span>
                <span class="n">func_grp</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="n">fg</span><span class="o">.</span><span class="n">species</span><span class="p">,</span> <span class="n">origin</span> <span class="o">-</span> <span class="p">(</span><span class="n">fg</span><span class="o">.</span><span class="n">coords</span> <span class="o">-</span> <span class="n">origin</span><span class="p">))</span>

        <span class="c1"># Remove the atom to be replaced, and add the rest of the functional</span>
        <span class="c1"># group.</span>
        <span class="k">del</span> <span class="bp">self</span><span class="p">[</span><span class="n">index</span><span class="p">]</span>
        <span class="k">for</span> <span class="n">site</span> <span class="ow">in</span> <span class="n">func_grp</span><span class="p">[</span><span class="mi">1</span><span class="p">:]:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">_sites</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">site</span><span class="p">)</span></div></div>


<div class="viewcode-block" id="StructureError"><a class="viewcode-back" href="../../../pymatgen.core.structure.html#pymatgen.core.structure.StructureError">[docs]</a><span class="k">class</span> <span class="nc">StructureError</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;</span>
<span class="sd">    Exception class for Structure.</span>
<span class="sd">    Raised when the structure has problems, e.g., atoms that are too close.</span>
<span class="sd">    &quot;&quot;&quot;</span>
    <span class="k">pass</span></div>


<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">),</span>
                       <span class="s2">&quot;func_groups.json&quot;</span><span class="p">),</span> <span class="s2">&quot;rt&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
    <span class="n">FunctionalGroups</span> <span class="o">=</span> <span class="p">{</span><span class="n">k</span><span class="p">:</span> <span class="n">Molecule</span><span class="p">(</span><span class="n">v</span><span class="p">[</span><span class="s2">&quot;species&quot;</span><span class="p">],</span> <span class="n">v</span><span class="p">[</span><span class="s2">&quot;coords&quot;</span><span class="p">])</span>
                        <span class="k">for</span> <span class="n">k</span><span class="p">,</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">json</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">f</span><span class="p">)</span><span class="o">.</span><span class="n">items</span><span class="p">()}</span>
</pre></div>

            <div class="clearer"></div>
          </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../../index.html">pymatgen 2020.7.3 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../../index.html" >Module code</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="../../pymatgen.html" >pymatgen</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">pymatgen.core.structure</a></li> 
      </ul>
    </div>

    <div class="footer" role="contentinfo">
        &#169; Copyright 2011, Pymatgen Development Team.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.1.2.
    </div>
<div class="footer">This page uses <a href="http://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script type="text/javascript">
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>

  </body>
</html>